Cool readme on your github profile page with github actions.
Tags: github, career, readme, markdown
Published: 2023-09-30 10:42:14

In the world of coding, there's one task many of us dread - writing documentation. Yet, when you start a new project or set up a fresh GitHub repository, those all-important markdown files beckon. Enter the GitHub profile README, a clever feature that lets you infuse your personal touch into your GitHub page. And when you combine this with the power of GitHub Actions, something magical happens: you craft a captivating portfolio-CV page that paints a vivid picture of who you are as a coder.

Creating an engaging GitHub profile with the help of GitHub Actions can be a game-changer for showcasing your skills and personality. While crafting a README for your profile might not be the most thrilling task, it's essential to present yourself effectively in the developer community. Combining GitHub Actions with your profile README allows you to create a dynamic portfolio-CV page that represents you authentically. In today's competitive job market, your CV is only part of the equation; your portfolio and interests matter too. 

Your CV is just the tip of the iceberg. Hiring managers are casting a wider net, scrutinizing your portfolio and even your interests. They rely on tools to pluck out pertinent information from resumes, but let's face it – most CVs are stubbornly resistant to easy parsing. Whether it's an ancient PDF or a beautifully designed but enigmatic image, it often doesn't cut it. The consequence? Even brilliant developers find themselves at the bottom of the hiring pile. That's where the profile README steps in. It's not just a CV; it's a user-friendly, easily indexed powerhouse of a developer's journey.It should include not just your CV but also links to your social profiles, blog articles, skills, certifications, GitHub stats, preferred repositories, and even a touch of personal flair to engage the reader.

In my opinion, a README page should have:

1.     Social and contact links.
2.     Blog articles on tech and ideas.
3.     Skills and certifications.
4.     GitHub stats and favorite repositories (if desired).
5.     An auto-generated CV.
6.     A relaxed section.
7.     Contact details.

Here in the article, I will try to describe my own path to create GitHub readme file. So, how do you create a GitHub README that shines? Start by establishing a profile repository bearing your GitHub username. My username is _dzmdre_, so I created a repository with the name _dzmdre_. I initialized the repository with _README_ and _.gitignore_ files. I cloned it down and opened it in my favorite editor. In this repository, introduce a _"readme.template"_ file, the secret sauce that fuels your dynamic README.

### Create a README Template
Create a new _“readme.template”_ at the root level of my repository. This is the file I will be editing manually, and readme will be auto-generated based on _“readme.template”_ and data received through the rest calls.

### Banner Image
Your README's visual appeal often starts with a banner image at the top. You can create a banner featuring a photo from a conference, along with your contact details. I haven’t found something suitable and have chosen some simple picture from [Canva](https://www.canva.com/) site. I added some necessary contacts data and my banner was ready. Back in my repository, I created a new root-level directory named assets, placed the image in the folder and added it in the _“readme.template”_ file.

```
[![Dmitry's GitHub Banner](./assets/GitHubHeader.png)](https://linktr.ee/drepin)
```

### Social Badges
Then, you can add social badges to your various online profiles using badges from [shields.io](https://shields.io).
You should have something similar to this:

```[![Twitter Badge](https://img.shields.io/badge/Twitter-Profile-informational?style=flat&logo=twitter&logoColor=white&color=1CA2F1)](https://twitter.com/drepindmitry)
[![LinkedIn Badge](https://img.shields.io/badge/LinkedIn-Profile-informational?style=flat&logo=linkedin&logoColor=white&color=0D76A8)](https://linkedin.com/in/dmitry-drepin-77107336)```

### The Introduction Section
Most of the GitHub readme files include only this main part.The main template is:

```
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: ...
```

People generally prefer not to delve into extensive self-reflections; it's more effective to demonstrate skills through certifications and the portfolio section. If visitors seek additional information about me, they can explore [my website](https://dzmdre.blogspot.com) or [LinkedIn profile](https://linkedin.com/in/dmitry-drepin-77107336). Keep it concise and straightforward.

### GitHub Stats & Wakatime plugin

You can add a lot of [Anurag Hazra‘s GitHub ReadMe Stats](https://github.com/anuraghazra/github-readme-stats) features:

**[GitHub Stats Card](https://github.com/anuraghazra/github-readme-stats#github-stats-card)**

By default, the stats card only shows statistics like stars, commits and pull requests from public repositories. To show private statistics on the stats card, you should deploy your own instance using your own GitHub API token.

**[GitHub Extra Pins](https://github.com/anuraghazra/github-readme-stats#github-extra-pins)**

GitHub extra pins allow you to pin more than 6 repositories in your profile using a GitHub readme profile.

**[GitHub Gist Pins](https://github.com/anuraghazra/github-readme-stats#github-gist-pins)**

GitHub gist pins allow you to pin gists in your GitHub profile using a GitHub readme profile.

**[Top Languages Card](https://github.com/anuraghazra/github-readme-stats#top-languages-card)**

The top languages card shows a GitHub user's most frequently used languages. Top Languages does not indicate the user's skill level or anything like that; it's a GitHub metric to determine which languages have the most code on GitHub. This card shows languages usage only inside your own non-forked repositories, not depending from who is the author of the commits. It does not include your contributions into another users/organizations repositories. Currently this card shows data only about first 100 repositories. This is because GitHub API limitations which cause downtimes of public instance.

**[Wakatime Stats Card](https://github.com/anuraghazra/github-readme-stats#wakatime-stats-card)**

[WakaTime](https://wakatime.com/) is committed to making time tracking fully automatic for every programmer. By creating opensource plugins for IDEs and text editors, it gives powerful insights about how you code. It is possible now demonstrate these statistics in your GitHub profile.
What’s next? Next up, showcase your skills, awards, and certifications.

### Skills, Awards, and Certifications:

Avoid using an unordered list for this section, as it can become challenging to read. Instead, the key is to categorize and group your skills and certifications, making them more organized and easier to manage. The specific edits required for this section depend on the number of skills, certifications, and other factors. If you have an extensive list, consider utilizing small badges from [shields.io](https://shields.io) where applicable and hide outdated information.

### Latest Blog Posts & random quote

In today's world, having more than just an impressive CV is essential; it's equally crucial to maintain a personal IT blog, sharing your insights and opinions. For programmers, a personal IT blog serves as an invaluable platform for various reasons.
Firstly, it's a stage to showcase their expertise, skills, and profound knowledge within the tech industry. Regular blog posts allow programmers to exhibit their problem-solving abilities, coding prowess, and innovative thinking, all of which are invaluable assets in their professional journey.
Secondly, a personal IT blog keeps programmers in sync with the ever-evolving industry trends and technologies. Writing about new tools, frameworks, or programming languages compels them to thoroughly research and understand these innovations, enriching their knowledge base.
Moreover, a blog becomes a repository for their learning experiences. Programmers can document their challenges, breakthroughs, and projects, creating a valuable resource not just for themselves but for the broader developer community. This knowledge sharing fosters collaboration, networking, and the overall growth of the IT community.
Lastly, a well-maintained IT blog elevates a programmer's professional credibility and can open doors to consulting opportunities, speaking engagements, or even job offers. It acts as a digital portfolio that potential employers or clients can consult when assessing the programmer's skills and expertise.
That's precisely why having links to your blog articles on your GitHub page is of paramount importance. It's a gateway for others to tap into your knowledge, experience, and thought leadership within the tech world.
To automate the process of updating your README with blog posts and a random quote, you can create a GitHub Action workflow. The workflow will dynamically fetch data and inject it into your _"readme.template"_ file. This keeps your profile fresh and engaging.
To inject my blog feed into the _README.md_ file, I followed [Renan Franca](https://dev.to/renanfranca) article [Create a Github stunning profile](https://dev.to/renanfranca/create-a-github-stunning-profile-by-dynamically-listing-your-recent-blog-posts-3g0j) 💫 (by dynamically listing your recent blog posts) 
The hard work will eventually be delegated to separate file that the GitHub Action workflow will run, but in order for that file to know where to inject the content, it requires a certain pattern in the template.
For now, I put the following under the blog post section in the _„readme.template”_ file:
<!-- BLOG-POST-LIST:START -->
<!-- BLOG-POST-LIST:END --> 
Very much like the blog post section, a GitHub Action workflow will run a script that will look for a pattern in the _„readme.template”_ file and inject a random quote.
I put the following pattern in the quote section:

```
> {quote}
>
> <p>{quote_author}</p>
```

To make this happen a GitHub Action workflow will run a script that will look for a pattern in the _„readme.template”_ and inject a random quote.

You should have 4 steps to create in _index.js_:

The _index.js_ File
There are four steps this file needs to complete:
·      Create a variable to reference the _README.template.md_ file

·      Make the request to the rest service

·      Look through the _„readme.template”_ content and replace the static patterns _({quote} & {quote_author})_ with the dynamic result of the API request

·      Create/replace the contents of the _README.md_ file with the updated _„readme.template”_ reference variable.

_Index.js_ file

```
require("isomorphic-unfetch");
const { promises: fs } = require("fs");
const path = require("path");

async function main() {
    const readmeTemplate = (
        await fs.readFile(path.join(process.cwd(), "./README.template.md"))
    ).toString("utf-8");

    const quote = await (
        await fetch("https://api.quotable.io/random")
    ).json();

    console.log(quote);

    const readme = readmeTemplate
        .replace("{quote}", quote.content)
        .replace("{quote_author}", `- ${quote.author}`)

    await fs.writeFile("README.md", readme);
}

main();
```

Create a workflow file _dynamic-injection-workflow.yml_ under the _.github/workflows_ directory:

```
name: Dynamic README injection
on:
  schedule: # Run workflow automatically
    # This will make it run every hour
    - cron: "0 * * * *"
    # Run workflow manually (without waiting for the cron to be called), through the Github Actions Workflow page directly
  workflow_dispatch:
permissions:
  contents: write # To write the generated contents to the readme

jobs:
  get-quotes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: 16.16.0
      - run: yarn
      - run: node .
      - name: Add to git repo
        run: |
          git config pull.rebase false
          git pull
          git add .
          git config --global user.name "GitHub Action"
          git config --global user.email "action@github.com"
          git commit -m "[Automated] README updated with new quote!"
      - name: Push
        uses: ad-m/github-push-action@master
        with:
          github_token: ${{secrets.GITHUB_TOKEN}}
  update-readme-with-blog:
    needs: get-quotes
    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:
          # Replace this URL with your rss feed URL/s
          feed_list: "https://dzmdre.blogspot.com/feeds/posts/default?alt=rss,https://dev.to/feed/dmitryd"
```

It will allow you to receive the latest blog posts from your site & update quote.
And Node execution here will trigger the _index.js_ file to do its magic.
Once you've added a workflow in GitHub, it becomes visible under **'Actions'** > **'All workflows.'** If you want to manually trigger the workflow and test its functionality, simply click on the **'Run workflow**' dropdown button. You can then choose to run the workflow on the main branch. However, keep in mind that the cron job you've set up will automatically execute this workflow every hour, ensuring it runs periodically.
Once the workflow successfully completes both of its designated tasks, you can view the final result on your GitHub profile. It's a seamless way to keep your profile updated and dynamic.
 
###Publish resume in JSONResume format at the Github Page
 
Another essential workflow involves the automatic generation of a CV file, which is based on a _resume.json_ file. JSON Resume stands as an open standard format, designed for crafting and sharing resumes or CVs in a structured and machine-readable manner. It harnesses the power of JSON to delineate various resume sections, encompassing personal details, educational background, work experience, skills, and more. JSON Resume empowers individuals to maintain a single source of truth for their professional history while facilitating the creation of customized resumes in diverse formats like HTML, PDF, or plain text. This versatility is bolstered by the availability of various themes and templates, ensuring a visually appealing and unique CV while preserving data in an organized format.
This format's adaptability and developer-friendly nature have made it a preferred choice among tech-savvy individuals who aim to craft compelling resumes that stand out. [JSON Resume ](https://jsonresume.org) also fosters open-source collaboration, enabling users to contribute themes and tools to the community. This collaborative approach ensures ongoing enhancements and personalization of resumes in a standardized fashion.
 
How to do this?
Create a file _publish-resume.yml_  under the _.github/workflows/_ directory with a following content:

```

# example GitHub workflow
name: Publish resume in JSONResume format as Github Page

on:
  push:
    branches: [ master ]
  schedule: # Run workflow automatically
    - cron: "0 1 * * *"
    # Run workflow manually (without waiting for the cron to be called), through the Github Actions Workflow page directly
  workflow_dispatch:
permissions:
  contents: write # To write the generated contents to the readme

jobs:
  check_run:
    runs-on: ubuntu-latest
    if: "! contains(github.event.head_commit.message, '[Automated]')"
    steps:
      - run: echo "${{ github.event.head_commit.message }}"

  build:
    runs-on: ubuntu-latest
    needs: check_run
    steps:
      - uses: actions/checkout@v2
      - uses: kelvintaywl/action-jsonresume-export@v1
        name: Export resume as HTML
        with:
          theme: macchiato
          resume_filepath: resume.json
          # modifies the index.html in-place
          output_filepath: docs/index.html
      - name: Commit published HTML
        id: commit
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          if [ -n "$(git status --porcelain docs/index.html)" ]; then
            git add docs/index.html
            git commit -m "[Automated] chore(docs/index.html): update resume page"
            echo "{exit_code}={0}" >> $GITHUB_OUTPUT
          else
            echo "{exit_code}={1}" >> $GITHUB_OUTPUT
          fi
      - name: Push changes
        uses: ad-m/github-push-action@master
        if: steps.commit.outputs.exit_code == 0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          branch: ${{ github.ref }}
```

The workflow should automatically generate the CV file on a daily basis or update it whenever there's a push event. If you wish to alter this behavior, you can reconfigure the cron job accordingly. To change the CV's appearance, simply adjust the _"theme"_ property to select a different style.
The generated CV file will be stored in the _"output_filepath"_ specified as _"docs/index.html."_ It's advisable to create an empty _"index.html"_ file within the directory beforehand.
Once you've executed this GitHub workflow, your CV will be automatically generated based on the content in your _resume.json_ file. To provide a link to your CV, you can use the following prefix: 

```
"My auto-generated <a href="https://htmlpreview.github.io/?https://raw.githubusercontent.com/dzmdre/dzmdre/main/docs/index.html">CV</a>"
```

If you have missed something please take a look on [my Github page](https://github.com/dzmdre).

In conclusion, a well-crafted **GitHub profile README** with **GitHub Actions** can help you stand out in the developer community. It's a versatile tool for showcasing your skills, sharing your thoughts, and presenting your professional history. By following these steps, you can create an impressive and dynamic GitHub profile that represents you effectively.
Thanks for reading! If you liked this article and want more content like this, make sure to follow me on [Twitter](https://twitter.com/drepindmitry)!A special thanks to @rahuldkjain and @gautamkrishnar, @renanfranca for building the awesome open source projects that I used on this post. Please, visit [rahuldkjain's project repository](https://github.com/rahuldkjain) and [gautamkrishnar's project repository](https://github.com/gautamkrishnar) and give it a star 🤩