Featured post: How I built this website

Skip to main content

Creating my GitHub README.md

Written by . Published on under the Web category.

My new GitHub profile README.md

A few months ago, GitHub introduced a feature that lets you create a custom README.md that shows on your profile homepage. I have known about this feature since it was first released but because I haven’t been using GitHub very much of late (well, the desktop interface anyway) I have not given the custom README.md feature much thought. However, it came to mind and I decided to try and create my own README.md for my profile.

To create a README.md that displays on your GitHub profile, you have to create a repository with the same name as your GitHub username. In my case, I created a repository called capjamesg. You can see the repository using the link below:

https://github.com/capjamesg/capjamesg

If you select the option to add a README.md file when the repository is created, you will get a README.md file with a heading already included as well as some guidance (in comments, so it is not visible) on what to include in your file. I glanced over this guidance but I already had an idea in mind: use the contents of my bio on my homepage. I decided this would be a good idea because I am happy with the bio on my homepage and I think it represents me well.

I added my bio to the README.md file and was happy. I then decided to list a few of the things that I would love to chat with people about, which was one of the suggestions in the guidance that came with the default README.md file. Then I got another idea: list my most recent blog posts in the README.md.

I ran a quick Google search and came across JasonEtco’s rss-to-readme project, a GitHub Action template that retrieves posts from an RSS feed on your blog and lets you add them to your GitHub profile. I used the template and tested it out. To do so, I copied the text from the “Usage” section of the rss-to-readme README.md file (which contains instructions on how to use the project, like any non-GitHub profile README). I did have to change the “on” line of code in the Action template so that it said the following:

on: push

This would let me see updates to my README.md immediately after pushing any change to my repository. This was important because I wanted to see the results immediately. The default template is set up so the README.md file is updated with new posts (if any are available in your RSS feed) at 8 am every morning, which was not ideal for testing. But after I got the project set up, I reverted the “on” code to its original setting so that my README.md file would update automatically every day at 8 am.

I then added the following text to my README.md file so that it would show the posts:

<!--START_SECTION:feed-->
...
<!--END_SECTION:feed-->

This code is from the “Usage” section of JasonEtco’s rss-to-readme repository. The “…” is replaced with your blog posts every time the GitHub Action runs. By default, five posts are shown, but you can update this if you want. The documentation for configuring the Action is in the rss-to-readme README.md file.

I did try to show the publish date of each post in the README.md file but I couldn’t get the dates to show in the way that I wanted them to. If someone figures out how to get the publishing date from the RSS feed and format it in a form like (January 1st, 1990) then please do let me know. I could only get the date as a timestamp, which was not worth displaying on my README.md file.

Here is how my GitHub profile looks now:

My new GitHub profile README.md

I have not delved too deep into the GitHub profile README.md feature but I’m happy with what I have. I might try again to show post publishing dates in my repository. If I do, I may share any solution I come up with on my blog. If you don’t already have a GitHub README.md file on your profile and have a spare few moments, consider setting one up. There seems to be a lot of potential for creativity in this one GitHub feature.

Go Back to the Top