How to create an awesome Github Profile README ?

Biya Paul — Mon, 25 Apr 2022 11:51:14 +0000

If you take a look of my GitHub profile, you’ll notice that it contains Github statistics, social network links and some more content, which makes my GitHub profile look more descriptive.

In this article, we’ll learn how to create a GitHub profile README, add impressive content and make a cron job to refresh it every (x) hours.

What is Github profile README

GitHub that allows users to use a Markdown file named README to write details about theirself, skills, social life and increase visibility. It’s shown at the top of your GitHub home page, above the pinned repositories. Here are some examples of information that visitors may find interesting, fun, or useful in your profile README.

An "About me" section that describes your work and interests
Contributions you're proud of, and context about those contributions
Guidance for getting help in communities where you're involved

Create a Github profile README

GitHub will display your profile README on your profile page if all of the following are true.

You've created a repository with a name that matches your GitHub username.
The repository is public.
The repository contains a file named README.md in its root.
The README.md file contains any content.

Add Awesome content to your Github profile

First, Open your repository with a modern Text Editor like VsCode

Now open a terminal to its directory and create a new npm project

npm init

We are going to use Mustache, which allows us to create a template and easily replace tags with data we will provide later.

npm i mustache

Create a mustache template
We are going to create a new mustache file in the directory.

touch index.mustache

Let's add some small content

My name is {{full_name}} and you can see my works <a href="https://bpmartdesign.tk">here.</a>

Notice the {{___}} tag? That’s how Mustache recognizes something can be placed there.

Generate README from mustache file template

First, create a index.js file, where we will write the code to parse data.

const Mustache = require('mustache');
const fs = require('fs');
const MUSTACHE_MAIN_DIR = './index.mustache';

/**
  * DATA is the object that contains all
  * the data to be provided to Mustache
  * Notice the "full_name" property.
*/
let DATA = {
  full_name: 'BIYA Paul'
};

/**
  * A - We open 'index.mustache'
  * B - We ask Mustache to render our file with the data
  * C - We create a README.md file with the generated output
  */
function generateReadMe() {
  fs.readFile(MUSTACHE_MAIN_DIR, (err, data) =>  {
    if (err) throw err;
    const output = Mustache.render(data.toString(), DATA);
    fs.writeFileSync('README.md', output);
  });
}
generateReadMe();

With that, you can now run node index.js in your terminal and it should generate a brand new README.md file in the same directory:

// Generated content in README.md
My name is BIYA Paul and and you can see my works here.

Commit and push everything. Now, you can see that your README.md displayed on your Profile page has been updated.

Add a CRON Job to generate your README periodically

So, finally you have increase your visibility by creating an awesome README.md file.
But you will surely not have the time to commit and push every day to make your profile up to date.

So, Github Actions has been done for us with a lot of function to automate our process.

With Actions, you can create workflows to automate tasks. Actions live in the same place as the rest of the code, in a special directory: ./.github/worflows.

$ mkdir .github && cd .github && mkdir workflows

In this ./workflows folder, create a ./main.yaml file that will hold our Action.

$ cd ./workflows && touch main.yaml

Be sure your branch name is master instead of main if not, please rename your principal branch to master

If its Okay, now you can fill your main.yaml file with this content

name: README build

on:
  push:
    branches:
      - master
  schedule:
    - cron: '0 */6 * * *'

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout current repository to Master branch
        uses: actions/checkout@v1
      - name: Setup NodeJs 13.x
        uses: actions/setup-node@v1
        with:
          node-version: '13.x'
      - name: Cache dependencies and build outputs to improve workflow execution time.
        uses: actions/cache@v1
        with:
          path: node_modules
          key: ${{ runner.os }}-js-${{ hashFiles('package-lock.json') }}
      - name: Install dependencies
        run: npm install
      - name: Generate README file
        run: node index.js
      - name: Commit and Push new README.md to the repository
        uses: mikeal/publish-to-github-action@master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Congratulations

You did it, Now you have a professionnal Github README profile, and it will be up to date every 6 hours

Remember, you can change the period by updating the line
- cron: '0 */6 * * *' by replacing 6 to x desired hours

What is Next ?

As you have seen, you can add more dynamic contents in your Github profile like
badges, github statistics and more.

Badges
The most important badge provider I recommend is Shield.io. There you can customize, build and redesign the provided badge according to your own design.

I am using them in mine like this

<h3>Things I code with ...</h3>
<p>
  <img  height="20" alt="React" src="https://img.shields.io/badge/-React-45b8d8?style=flat-square&logo=react&logoColor=white" />
  <img  height="20" alt="Vue Js" src="https://img.shields.io/badge/Vue.js-35495E?style=for-the-badge&logo=vue.js&logoColor=4FC08D" />
  [...]
  <img  height="20" alt="Laravel" src="https://img.shields.io/badge/Laravel-FF2D20?style=for-the-badge&logo=laravel&logoColor=white" />
</p>

Links and more
If you want to add links, images, tables and anything else, you can just update your index.mustache as template according to what you need as HTML Content (Without CSS style).

Github statistics
You can also show your Github statistic related to a repository, organization or profile there. Below is an example of github statistic card I use on my github page

<img alt="bpsmartdesign's GitHub stats" src="https://github-readme-stats.vercel.app/api?username=bpsmartdesign&count_private=true&show_icons=true&theme=onedark" />

You can get more details here.

References

Github doc
Thomas Guilbert Article
Supritha Ravishankar Article

Thank you for reading! 🙌

Share your amazing GitHub profile in the comments down below for the world to see! :)
My Github | My Portfolio