How to create a self-updating GitHub profile README

About profile READMEs

README files are added to a repository to communicate important information about your project. They are usually the first thing a visitor will see when visiting a repository and a core part of well-documented open-source software.

GitHub released the profile readme feature in the middle of 2020. They offer a nice way to share information about yourself with the community and are shown at the top of your profile page, above pinned repositories and other information. My current profile readme displayed on my GitHub profile at the time of writing this article looks like this:

Creating a profile readme

To create a README file that is displayed on your GitHub profile, you need to follow these steps:

1. Create a repository that has the same name as your GitHub account. Mine is located at github.com/codepunkt/codepunkt.
2. Ensure the repository is public.
3. Create a README file in the project root.

If the README file doesn’t have an extension, it is assumed to be written in GitHub flavored Markdown. It is also possible to write them in a few other languages like AsciiDoc or Org—but you need to add the right file extension for those to be parsed correctly. While you’re working on the contents, you can set your repository to private to not show something unfinished in your profile.

Make it stand out

If you choose to initialize the new repository with a README file, the default contents have some great tips on things to include:

### Hi there 👋

<!--
**codepunkt/codepunkt** is a ✨special✨ repository because
its `README.md` (this file) appears on your GitHub profile.

Here are some ideas to get you started:

- 🔭 I’m currently working on ...
- 🌱 I’m currently learning ...
- 👯 I’m looking to collaborate on ...
- 🤔 I’m looking for help with ...
- 💬 Ask me about ...
- 📫 How to reach me: ...
- 😄 Pronouns: ...
- ⚡ Fun fact: ...
-->

You could just throw in text-based information about your work, your contact information and your interests, but you can also add emojis and images to spice things up. Even animated GIFs and SVG images with animation work fine.

Automatically updating with my latest blog posts

I decided to link to my latest blog posts in my profile readme. Because I don’t want to update them manually, I thought about a process to update them automatically. The leading roles in this process are played by the RSS feed of my blog and GitHub Actions. GitHub Actions can schedule workflows to run regularly using crontab format. Workflows for a repository are defined in the .github/workflows folder as .yml files.

The workflow to automatically update my readme with the latest blog posts is defined in a build.yml that defines the workflow name and the occasions when it runs in the first part:

name: Build README.md

on:
  # on push to the repository
  push:
  # can be triggered manually
  workflow_dispatch:
  # on a schedule at minute 6 and 36 of each hour
  schedule:
    - cron: '6,36 * * * *'

The actual definition of the workflow is defined afterward:

jobs:
  build:
    runs-on: ubuntu-20.04
    steps:
      - name: Check out repository
        uses: actions/checkout@v2

      - name: Set up Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '14'

      - name: Configure NPM caching
        uses: actions/cache@v2
        with:
          path: ~/.npm
          key: npm-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            npm-

      - name: Install NPM dependencies
        run: npm i

      - name: Update README.md
        run: |-
          node src/build-readme.js
          cat README.md

      - name: Commit and push if changed
        run: |-
          git diff
          git config --global user.email "bot@example.com"
          git config --global user.name "README-bot"
          git commit -am "chore: updated content" || exit 0
          git push

This performs a git checkout of the repository, sets up Node.js and npm, installs the required npm dependencies and runs a Node.js script that performs the actual update of my profile readme. Afterward, it commits and pushes the freshly updated file back into the repository.

So how does the Node.js script work?

### Latest blog posts

<!-- blog start -->

- [First blog post](https://example.com/article-1)<br/>
  First blog post excerpt
- [Second blog post](https://example.com/article-2)<br/>
  Second blog post excerpt
- [Third blog post](https://example.com/article-3)<br/>
  Third blog post excerpt

<!-- blog end -->

const zone = require('mdast-zone');

function replaceBlogposts(feedItems) {
  return () => (tree) => {
    zone(tree, 'blog', (start, nodes, end) => {
      return [
        start,
        {
          type: 'list',
          ordered: false,
          children: feedItems.map(itemToMarkdown),
        },
        end,
      ];
    });
  };
}

function itemToMarkdown({
  title,
  link,
  contentSnippet: snippet,
  pubDate,
}) {
  return {
    type: 'listItem',
    children: [
      {
        type: 'paragraph',
        children: [
          {
            type: 'link',
            url: link,
            children: [{ type: 'text', value: title }],
          },
          { type: 'html', value: '<br/>' },
          {
            type: 'emphasis',
            children: [{ type: 'text', value: snippet }],
          },
        ],
      },
    ],
  };
}

const { promisify } = require('util');
const { writeFile } = require('fs');
const { join } = require('path');
const RssParser = require('rss-parser');
const vfile = require('to-vfile');
const remark = require('remark');

const rssParser = new RssParser();
const readmePath = join(__dirname, '..', 'README.md');

(async () => {
  const feed = await rssParser.parseURL(
    'https://codepunkt.de/writing/rss.xml',
  );
  const file = await remark()
    .use(replaceBlogposts(feed.items))
    .process(vfile.readSync(readmePath));
  await promisify(writeFile)(readmePath, String(file));
})();

Interesting profile README examples

To give you some inspiration, here are a few great examples of GitHub profile readmes at the time of writing (March 2021):

• Swyx implemented a mechanism that lets users endorse him for his skills.
• Jhey has a nice SVG image with a CSS keyframe loop.
• Ross has a README that allows you to play an ancient mesopotamian board game.
• Martin has a nice overview of his GitHub stats and the technologies and tools he uses.

Conclusion

Hopefully, this article gave you enough inspiration to create your own GitHub profile README.

Whether it’s simple or complex, static or automatically updated, informative or playful—it will stand out more than a plain GitHub profile and you can learn a thing or two while creating it!