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:
- Social and contact links.
- Blog articles on tech and ideas.
- Skills and certifications.
- GitHub stats and favorite repositories (if desired).
- An auto-generated CV.
- A relaxed section.
- 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 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.
[](https://linktr.ee/drepin)
Social Badges
Then, you can add social badges to your various online profiles using badges from shields.io.
You should have something similar to this:
[](https://twitter.com/drepindmitry)
[](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 or LinkedIn profile. Keep it concise and straightforward.
GitHub Stats & Wakatime plugin
You can add a lot of Anurag Hazra‘s GitHub ReadMe Stats features:
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 allow you to pin more than 6 repositories in your profile using a GitHub readme profile.
GitHub gist pins allow you to pin gists in your GitHub profile using a GitHub readme profile.
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 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 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 article Create a Github stunning profile 💫 (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:
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 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.
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!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 and gautamkrishnar's project repository and give it a star 🤩
Top comments (1)
Absolutely loved the article, Dmitry! It’s amazing to see how GitHub Actions can be leveraged to create such engaging READMEs. And oh, it was a pleasant surprise to see my name mentioned too! Your step-by-step tutorial is a boon for the dev community. Kudos to you! 🎉👏😄 Keep rocking the open-source world! 🚀