How to create a self updating GitHub Readme

By on 21 November 2022

It was about time to give my GitHub profile a nice intro so inspired by Simon Willison’s blog post I decided to make an intro Readme that auto-updates.

First I made a GitHub repo called bbelderbos, my username. That’s how it works: GitHub defaults to showing the Readme.md of your username’s repo on your profile page.

Now the auto-updating part:

  1. Looking at Simon and Brett‘s repos I started with a script to parse the Pybites article json and my Python tips repo (reminder: you learn so much by reading other developer’s code!)
  2. It created this template that the script updates and saves to Readme.md.
  3. I set up a job with GitHub Actions to auto-update it (again, Brett’s repo was of great help here).

Looks nice no?

Screenshot 2022 11 21 at 10.19.44

Some other things I learned:

  • pip-tools: this nifty tool let’s you specify your dependencies in a requirements.in file.
    pip-compile makes a “rich” requirements.txt file where you not only see the pinned dependencies but also how they depend upon each other (for which I used pipdeptree previously).
  • Get it working first, then refactor: to get the last 5 tip titles I was making 5 httpx requests to GitHub.
    It later occurred to me that I already have these tip titles in the index.md file of the repo, so I refactored it to parse this file reducing 5 web requests to 1, making the build-readme.py script almost twice as fast (2.7 -> 1.5 seconds).
    Lesson / reminder: get it working first, then optimize.
  • Some other cool things I used with this script: type hints, jinja templating, pathlib to read + write files, a bit of regex and functions to make the code more modular.

I hope this inspires you to not only make a “Hi there” Readme yourself, but also to try to keep it updated by pulling in other data sources that are relevant for you (e.g. your blog feed).

Happy coding and sharing!

Want a career as a Python Developer but not sure where to start?