GitHub Profile README

Aug 18, 2020

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

In the main content section the popular repositories, contribution map, activity radar graph and contribution snippet list is shown. There’s a new optional section situated on the top of this default main content section. The way of configuring this section is the popular method used for your repositories as well: a Markdown marked up README file. In the name of convention by configuration that README file has to be placed into a repository named exactly as the user’s username (it is case sensitive!).

Markdown could offer 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 which use serverless functions use the vercel.app service. There is a long list of features and profiles collected in this repository for example purposes: awesome profile readmes. (Note: have no fear if you don’t have a customized Profile README that’s not a problem: 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, 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 flare image, which provides and overall reputation summary of all my StackExchange accounts. This is not a serverless function, but it’s 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 badges
  4. Recent blog posts: this is a GitHub Workflowgenerateddynamic 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 organization’s repositories, however many great projects are hosted within GDG Fresno, Csaba Consulting, or othernotable organizations.
  6. A StackOverflow larger 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 which show my GitHub stats and my repository language stats.

All of that is open source. Two blog posts which got me going: by Martin Heinz and by Monica Powel.

Comments loading...