GitHub recently released a feature that allows users to create a profile-level README.md file, that is displayed on your profile page, above repositories.
That’s a great feature you can use to display more information about yourself and your work, especially because it allows more content than the regular profile bio.
You might have noticed how people went crazy and are already pushing the limits of what can be done with Markdown and GitHub!
Above is my GitHub README at the time of writing this article.
I use it to tell it more about myself, show a list of my Open Source Projects and their status. Which is also useful for me as I can see quickly if I have any new open issues on them.
Now, more exciting, I made it self-updating, so I can give “live” information about the city where I live, Stockholm:
Using Puppeteer, I fetch the 3 latest pictures posted on @visitstockholm Instagram account,
I retrieve the weather information, temperature and daylight hours with the OpenWeatherMap,
While you are quite limited with Markdown, there are still a lot of cool things you can do!
In this tutorial, you are going to create your own README.md file for your GitHub Profile and learn how to make it dynamic, using GitHub Actions!
If you feel stuck or lost, check how I did it in my repository.
Create a new repository
First thing first, to unlock this feature, you need to create a new repository. It needs to be named the same name as your GitHub username.
You will notice that GitHub informs you of how special this new repository is!
Press enter or click to view image in full size
If you check the Initialize this repository with a README checkbox, then you should already see something if you go back to your Profile page.
Setup the project
Let’s make this README.md a bit more dynamic!
Clone the repository to your computer and 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
Create a new mustache file in the directory.
$ touch main.mustache
Open it and fill it with …anything your want :).
Let’s keep it simple for now:
My name is {{name}} and today is {{date}}.
Notice the {{___}} tag? That’s how Mustache recognizes something can be placed there.
Generate README.md file from a Mustache template
Create a index.js file, where we will write the code:
$ touch index.js
Fill it with the code below:
// index.js
const Mustache = require('mustache');
const fs = require('fs');
const MUSTACHE_MAIN_DIR = './main.mustache';
/**
- DATA is the object that contains all
- the data to be provided to Mustache
- Notice the "name" and "date" property. / let DATA = { name: 'Thomas', date: new Date().toLocaleDateString('en-GB', { weekday: 'long', month: 'long', day: 'numeric', hour: 'numeric', minute: 'numeric', timeZoneName: 'short', timeZone: 'Europe/Stockholm', }), }; /*
- A - We open 'main.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 Thomas and today is Thursday, July 23.
Awesome! Commit and push everything. Now, you can see that your README.md displayed on your Profile page has been updated.
Generate your README automatically with Github Actions:
That’s great but you don’t want to be having to commit a new version of your README.md every day. Let’s automate this!
We are going to use GitHub Actions for that. If you have never used it before, this is going to be a good first project.
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
Fill it with this content:
This Action has one Job, build , that runs on the specified machine, ubuntu-latest .
Lines 3 to 8 define when is triggered this action:
On every push to the Master branch,
Or on a specified schedule, here 6 hours.
The scheduler allows you to trigger a workflow at a scheduled time. The cron syntax has five fields separated by a space, and each field represents a unit of time.
If you want to know more about it and set your own schedule, read the Scheduled Events documentation.
When triggered, this job will execute the steps one after the other.
For the rest of the file, read what I wrote next to name: to understand what is happening for each step.
That’s it!
Commit and push your work to GitHub and you are done! Every 6 hours, the Action will be triggered, generate a new README.md file, and push it to the master branch.
Now, this is the most simple example I could come up with and I kept it simple to only talk about how to make your personal README.md automatically generated.
Let’s see some examples of what you can do:
