GitHub Profile README

Aug 18, 2020

GitHub has a relatively new feature called "Profile README". A GitHub user’s profile page is meant to provide a concise and comprehensive summary of their presence, activity, and achievements on the GitHub platform. In the left column, the user’s standard profile data is visible, such as a short summary, optional social media account references, and a public organizations list.

In the main content section, popular repositories, the contribution graph, an activity radar graph, and a contribution snippet list are shown. There’s a new optional section situated at the top of this default main content section. The way to configure this section is the popular method used for repositories as well: a Markdown-formatted README file. By convention over configuration, that README file has to be placed into a repository named exactly after the user’s username (it is case-sensitive!).

Markdown allows images and several creative elements to be featured in a README. It can really spice things up if serverless functions are used to populate README areas with dynamically fetched data. The customizations I saw that use serverless functions rely on the vercel.app service. There is a long list of features and profiles collected in this repository for inspiration: awesome profile readmes. (Note: have no fear if you don’t have a customized Profile README; that’s not a problem, as the standard GitHub profile will be shown, which still provides a smorgasbord of information.)

I assembled my profile by examining other profiles. I didn’t want too many graphical distractions; instead, I wanted to feature my skills, blog, and the projects I find important. In the end, my customized GitHub README consists of the following parts at the time of writing:

  1. A StackExchange flair image, which provides an overall reputation summary of all my StackExchange accounts. This is not a serverless function, but a dynamic image provided by StackExchange.
  2. A list of social media badges, using img.shields.io.
  3. Technology badges, also using img.shields.io.
  4. Recent blog posts: this is a GitHub Workflow-generateddynamic section. This is an interesting one: the generator function runs once a day and refreshes the data between the BLOG-POST-LIST:START and BLOG-POST-LIST:END XML comment tags.
  5. Projects worth mentioning: this is a static section hand-curated by myself. Several stats don’t look into my organizations’ repositories; however, many great projects are hosted within GDG Fresno, Csaba Consulting, or othernotable organizations.
  6. A larger StackOverflow flair which shows purely my StackOverflow stats (the top one is a summary of StackExchange accounts); this is not serverless, but the image is dynamically generated by StackOverflow.
  7. The last two widgets are serverless vercel.app features that show my GitHub stats and my repository language stats.

All of that is open source. Two blog posts that got me going were by Martin Heinz and Monica Powell.

Comments loading...