ElianCodes

← Back to blog

Published on 08/26/2021 11:48 by Elian Van Cutsem

Add your blogposts to your Github README

Github profile README’s are a very cool and personal way to tell something about yourself or your code. One of the downsides to this is that it depends on a static format. Well, this is not necessarily true. Through the power of code and Github Actions, we can use JavaScript (or another language) and generate a static README.md file. Here’s a little guide on how I added my latest blogposts to my Github profile.

What’s a Github README

Usually a README is created in a repository to explain what is does or to write some documentation about the project. Github introduced this some time ago to also work on Github Personal Profiles. At the moment the README doesn’t work yet on business and organisation accounts. You can check out the Github profile README page on their own documentation site here.

A Github profile README is a cool way to tell something about yourself. It can contain some links to your social accounts or a simple “about me” section. Basically, since it’s written in Markdown, it can be anything you want it to be. Markdown has some cool features, it can also contain HTML tags, so you could use it to show of some of your cool HTML-table skills like its 1997.

Now, it’s cool to build a static Markdown README.md, but it’s even cooler to write some code that generates your README with Github Actions or similar.

What is Github Actions

Github Actions is a CI-CD to build, test and deploy your code right from your repository on Github. Building a workflow on Github Actions is really easy. It’s nothing more than just a simple .yml file in the .github/workflows folder in your repository. If you need more information about what Github Actions is, you can check their own website.

How can we generate a README with code

In the following section I’ll use JavaScript to demonstrate how to generate a README file, but it basically could be any language as long as your workflow in Github Actions supports it.

Theoretical solution

Actually it’s not that hard. We can create a template file called README.raw.mdor something similar and read it in our code. Then we can use a script to manipulate the content inside the template and write it back as a static README.md file.

Build your template

Here I’ll use a simple example, feel free to go crazy and make the sickest things!

You’ll need some kind of way to show that something is a variable, so lets use a simple syntax:

# My Github README

Hello there! I'm {{name}} and I'm {{age}} years old

a markdown processor would display it right as it’s written, but by using code, we can replace the variables.

Write the code

First of all, create a file index.js in the root of your repository and add something like this:

const { promises: fs } = require("fs");
const path = require("path");

// Read the template and store it as a variable
async function main() {
  const template = (
    await fs.readFile(path.join(process.cwd(), "./README.raw.md"))
  ).toString("utf-8");
}
main();

// Creating a simple object to use
const elian = {
  name: "Elian",
  age: 21,
};

// Inject the content
const staticReadme = readmeTemplate
  .replace("{{name}}", elian.name)
  .replace("{{age}}", elian.age);

// Let's write the file
await fs.writeFile("README.md", staticReadme);

Now, when you run index.js it will output a static file readme.md with the replaced variables.

Create a workflow

create a new workflow file under .github/workflows/readme.yml

name: Dynamic README
jobs:
  inject:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Inject Variables
        uses: actions/setup-node@v1
        with:
          node-version: 14.6.0

      - run: yarn

        # Lets run the index.js
      - run: node index.js

        # Push the static file
      - name: Add to git repo
        run: |
          git config pull.rebase false
          git pull
          git add .
          git config --global user.name "Your Name"
          git config --global user.email "Your E-Mail"
          git commit -m "[Automated] README updated with variables"
      - name: Push
        uses: ad-m/github-push-action@master
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

Add blogpost list using Github Actions and no code

Fetch your blogposts using RSS

While researching a way to display my own blogposts on my README, I came across a cool bot called “Blog Post Workflow”, link to marketplace here. This bot will basically fetch the RSS feed of any blog you want it to and place the latest blogposts and links in your README.md file. To do this it also uses a Github Actions workflow, so you can integrate it with your own workflows.

Prepare your README

It’s really easy to use, firstly you just put an HTML comment in your README file as follows:

## My cool blog posts

<!-- BLOG-POST-LIST:START -->

<!-- BLOG-POST-LIST:END -->

The bot will basically use the comments as a guide on where to place the list of your blogposts.

Set up the workflow

Now that you’ve told the bot where to add the blogposts, let’s create the workflow

Create a new file .github/workflows/.blogposts.yml and add the following contents:

# Name can be anything you want
name: Latest blog post workflow
on:
  schedule: # Run workflow automatically
    - cron: "0 * * * *" # Runs every hour, on the hour
  workflow_dispatch: # Run workflow manually with a trigger
jobs:
  update-readme-with-blog:
    name: Update this repo's README with latest blog posts
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: gautamkrishnar/blog-post-workflow@master
        with:
          # you can change this to your own RSS feed
          feed_list: "https://www.elian.codes/blog.xml"

When this workflow is committed and pushed to your repository, it will search for an update every hour and make changes to the README.md file accordingly.

## My cool blog posts

  <!-- BLOG-POST-LIST:START -->

- - [🥳 Describe your commits using Gitmoji](https://www.elian.codes/blog/20-08-21-describe-your-commits-using-gitmoji/)
- - [🚀 Using Surge.sh to quickly deploy a static site](https://www.elian.codes/blog/using-surge-to-quickly-deploy-a-static-site/)
- - [✨ Moving on from Netlify to Google Cloud](https://www.elian.codes/blog/moving-on-from-netlify-to-google-cloud/)
- - [💄 Adding Google Fonts to your NuxtJS site](https://www.elian.codes/blog/adding-google-fonts-to-your-nuxtjs-site/)
- - [💄 Writing your own style components with TailwindCSS and Sass](https://www.elian.codes/blog/writing-your-own-components-with-tailwind-sass/)
  <!-- BLOG-POST-LIST:END -->

Some extra configuration options

Out of the box, the bot will fetch the latest 5 posts and sort them on time created, but if you want it to do other stuff, you can. Here’s a little list on options:

For more options, check the marketplace page.

Written by Elian Van Cutsem

← Back to blog

Recent Blogposts

  • So, I'm leaving vBridge

    So, I'm leaving vBridge

    After spending a couple of years at vBridge Cloud, I'm leaving the company. I've worked at vBridge eversince I graduated. Now, It's time for a new adventure! I'm joining the DX-team at Astro full-time!

  • Becoming an Astro maintainer

    Becoming an Astro maintainer

    Since a week, I'm an Astro maintainer, in this post, I describe the process and my start in open source. I also give some insight in what I'm planning to work on.

  • 🍱 Brutal: A theme for Astro

    🍱 Brutal: A theme for Astro

    Brutal is a minimal neobrutalist theme for Astro. It's based on Neobrutalist Web Design, a movement that aims to create websites with a minimalistic and functional design. It has some integrations like Image Optimization, RSS, Sitemap, ready to get your SEO done right.

  • 🎤 Am I an international public speaker now?

    🎤 Am I an international public speaker now?

    A few weeks ago, I gave my first international keynote talk at JSWorld in Amsterdam. In this blogpost, I wanted to share some insights about the conference and my talk.

  • ✨ Building Blog tag index pages in Astro

    ✨ Building Blog tag index pages in Astro

    I wanted to add blog tag collection pages to my website. This way, people could filter on tags I used in my blog posts. Here is a guide on how I implemented it.

  • 🎉 I started from scratch (again)

    🎉 I started from scratch (again)

    I started rebuilding my personal website from scratch in Astro again, no dependencies, no frameworks, no nothing. This to decrease technical debt and make full use of the newer Astro features.