WTF is a GitHub Profile README.md

Jacob Shuman — Sat, 24 Aug 2024 12:37:02 +0000

TL;DR

It’s a markdown file rendered on your GitHub profile.
Needs to be created in a special public repo with the same name as your GitHub username.
Can be used to display your skills and stand out to recruiters.

What is a profile README?

A markdown file that can be displayed on your GitHub profile (for more info check the docs).

How can I create one?

Go to the repository creation page here (https://github.com/new).
The repository name should be the same as your username. You can find your username by clicking on your profile icon in the top right corner and then looking at the text at the top of the sidebar (in the images below my username is jacob-shuman).
You should see a message like this underneath the repo name if the name is correct: Ensure the repository is public and the Add a README file option is enabled.
Create the repo and edit the generated README.md file.
There's no additional configuration necessary, the latest version of the README.md file on the default branch will be displayed in your profile at https://github.com/GITHUB_USERNAME.

A few notes

The README.md file on the repo's default branch will be used. If you change the default branch the profile will immediately render the new default branch's README.md.
The file must be named README.md for the profile to render it correctly. Using README instead of README.md will display the file on your profile but will be rendered as plain text😬.

What should I include in it?

Technically you can put anything in it (it’s just a standard GitHub-flavoured markdown file).

My advice is to think about your motivations:

If you plan on showing it to recruiters consider making it pop somehow.
- You could embed a game such as tic-tac-toe or chess, check out this README with an embedded connect-4 game powered by issues and GitHub Actions.
- You could add a counter to track how many people have visited your profile, read this article by Ryan Lanciaux for instructions on how to get started.
- For more examples check out Awesome GitHub Profile READMEs by abhisheknaiidu.
You could write about your development journey to inspire others.
If you want to make it look a bit fancier you could add some nicely styled badges! There are generators for static and dynamic badges like https://badgen.net/, https://shields.io/, and https://forthebadge.com/.
- You can make your own too, a badge is just a markdown-rendered image.
You can include social media links (although you should be able to also add them when editing your GiHub profile).
Include a list of technologies that interest you and show off projects you are proud of (including screenshots!). This is helpful for recruiters or other devs to quickly understand what you know, enjoy using, and the kinds of experience you have.
Include links to blog posts or any other creative work you have.

I built mine with a few ideas:

I wanted a simple layout thats well-organized yet might standout to recruiters.
The content should be direct (I wanted to limit my use of long-form text).
I'd like to talk about my motivations as a developer and the tech I’m both experienced with or interested in.

Dark Mode

It's possible to render markdown elements conditionally:

This is not exclusive to profile READMEs! Any markdown file can use these methods to render elements based on users' theme preferences.

HTML `media` attribute

Some HTML elements can be used directly in markdown when there isn't markdown syntax available for a particular feature (like underscoring). There is a media attribute for some HTML elements to render them based on a media query.

For example, I render this HTML badge.

<a href="https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/html-202020?style=for-the-badge&logo=html5" />
    <img alt="HTML badge" src="https://img.shields.io/badge/html-f0f0f0?style=for-the-badge&logo=html5" />
  </picture>
</a>

Based on this picture element the light version is used by default.

  <img alt="HTML badge" src="https://img.shields.io/badge/html-f0f0f0?style=for-the-badge&logo=html5" />

The dark version is included using a source element and the media attribute. I use the prefers-color-scheme media feature to check if the user's theme preference is dark.

 <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/html-202020?style=for-the-badge&logo=html5" />

Avoid `#gh-light-mode-only` and `#gh-dark-mode-only`

There is an older deprecated method to conditionally render images using the #gh-light-mode-only and #gh-dark-mode-only url fragments.

The old method of specifying images based on the theme, by using a fragment appended to the URL (#gh-dark-mode-only or #gh-light-mode-only), is deprecated and will be removed in favor of the new method described above.
Source (GitHub Docs)

Dark/Light mode screenshots

My profile has a header image and lots of badges, all of which are responsive to users' theme preferences:

Dark mode

Light mode

Thanks for reading this far!

This was my first blog post so I appreciate you reading this far. Please give me some honest criticism if you found something wrong with it so I can improve for next time.

DEV Community: Jacob Shuman