Beautifying your Github Profile / Readme files

Introduction #

For those of you who are not aware. We can customize our Github profile by creating a README.md file in our profile repository.

If your Github profile is Jh123x, you will have to create a repository with the name Jh123x and add a Readme.md file to it. The contents of the Readme.md will be displayed on your Github Profile as seen above.

Now that we have introduced how we can setup our profile, let’s see how we can beautify it.

Designing your profile #

I will be splitting this section into a few parts:

1. The base Readme file
2. Time based updates
3. Others

The base Readme file #

To start designing your Github profile, lets start with the Github Profile Generator Tool.

This tool allows us to customize our profile header, includes links to our socials, and even shows us statistics about our Github profile. This provides us a good starting point for our Github profile.

Time based updates #

The next step is to make our profile dynamic. We can do this by adding a Github Action that updates our profile every day. To find out more about how this works, you can take a look at my previous blog post.

A good tool to look into is Readme Scribe. This tool updates your Readme file with the latest information about your Github profile / website.

In the next section, we will walk through how to set it up.

Setting up Readme Scribe #

Setup the Github Action #

name: Update README

# When to run the job
on:
  push:
  schedule:
    - cron: "0 * */4 * *"

# What to do when the job runs
jobs:
  markscribe:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@master

        # Updates the README.md file
      - uses: muesli/readme-scribe@master
        env:
          GITHUB_TOKEN: ${{ secrets.PERSONAL_GITHUB_TOKEN }}
        with:
          template: "templates/README.md.tpl"
          writeTo: "README.md"

        # Commits the changes to the repository
      - uses: stefanzweifel/git-auto-commit-action@v4
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          commit_message: Update generated README
          branch: main
          commit_user_name: readme-scribe 🤖
          commit_user_email: actions@github.com
          commit_author: readme-scribe 🤖 <actions@github.com>

The 1st step is to create a .github/workflows/update-readme.yml file in your repository using the yaml snippet above.

Setting up the README.md.tpl file #

The next step is to create a templates/README.md.tpl file in your repository. This is the file that will be used to generate your README.md file.

There are a few special templates that you can use within the README.md.tpl file.

{{range recentPullRequests 3}}
- [{{.Repo.Name}}: {{.Title}}]({{.URL}}) ({{.State}}): {{.Repo.Description}} ({{humanize .CreatedAt}})
{{end}}

This snippet above shows how you can use the recentPullRequests template to show the 3 most recent pull requests that you have made.

Each section within the {{ and }} is a template that you can use to generate your README.md file.

You can find more information about the templates that you can use here

To see some of the other templates that I use, you can take a look at my profile repository.

Setting up the PERSONAL_GITHUB_TOKEN secret #

Next, we have to setup the PERSONAL_GITHUB_TOKEN secret in our repository. I have used the old personal access token method to update my README.md file. This will be the one I will be using in this blog post.

Settings Page #

Visit your settings page here: https://github.com/settings/profile

Click on developer settings at the bottom of the page

Generating a new token #

Click on Generate new token and give it the repo scope.

Ensure the following scopes are selected:

1. public_repo
2. read:org
3. read:user
4. repo:status

After you have generated the token, write it down somewhere safe.

Adding the token to your repository #

Go to you repository settings page and click on Secrets and Variables.

Set the secret name as PERSONAL_GITHUB_TOKEN and the value as the token you generated earlier.

Your page is now ready to go.

Conclusion #

In this blog post, we have seen how we can beautify our Github profile by creating a README.md file in our profile repository. These techniques can also be used to beautify your project README.md files as well.

If you want to do more fancy stuff, you can take a look at the Useful Links section below.

This is a short post to get my pace back on track. Hopefully, I can start writing more frequently.

Until next time, happy coding!

Useful Links #

Here are some other tools that you can use to improve your github repositories.

1. Todoist-readme: Adds your todoist status to your github profile.
2. Blog Post Workflow: Updates your blog post’s information on github.
3. Github Readme Generator: Generates a github profile readme file.
4. Hits: Shows the number of times your repository has been viewed.
5. Github Metrics: Shows your github metrics.
6. Readme Scribe: Generates a readme file for your repository and updates it automatically using github actions.