Github gives us the opportunity to personalize our profile – the page where our pinned repositories are – with a custom README.md that introduces who we are as developers. In this article, we take a look at steps to create a README file for your profile page and go over how to use Github-flavored Markdown to create the README.
Step 0: Create New Repository
To initialize your profile page with your markdown file, navigate to your repositories page and click on the green “new” button in the upper right hand corner of your screen.
Step 1: Repository Settings
Fill out the “Repository name” field with your Github username. Your handle must match the “Owner” field just to the left of the repo name field. Click the checkbox that indicates you would like to initialize the repository with a README. Finally, click on “Create Repository”.
Once the repository is created, you’ll be taken to your personal repository where you will see a README.md that was committed to your repo with some default text. Click on the “Edit” icon in the upper right hand corner of the preview (it looks like a pencil) and you’ll be taken to a page where you can flip between the actual markdown for your file and the preview of how it will look on your page.
Step 2: Editing Your README.md
For this step, you have a couple of options. If you are comfortable with working in an IDE, like Vim, Visual Studio Code, or Atom, you can clone and work on this file there. For the purpose of this article, we use Github’s built-in text editor because we have the ability to preview the changes made before they are committed.
Writing Markdown for Github
Github has its own Markdown dialect. Markdown helps create structured documents for email and discussion boards without having to use Hypertext Markup Language (HTML). Github’s Markdown is known as the Github-Flavored Markdown (GFM).
The basic purpose of this version is to sanitize and process Markdown to ensure the security and consistency of Github’s site. This means most of the Cascading Style Sheets (CSS) you use in traditional markdown may not be compatible with GFM. CSS is still available to us, but much of it is stripped away in the post-processing stage.
As you construct the important components you want to display in your Github profile, keep in mind of what to do if the bio was a traditional HTML file and follow that convention as best as you can.
Outside of these guidelines, your creativity and what you can come up with are what matter!
Here is an example using my Github profile:
How It Looks:
I completed this profile in about an hour after I realized the differences between Markdown and GFM. There are some little idiosyncrasies that I learned in the process, i.e: that CSS doesn’t really work in GFM. One helpful resource library to me is the docs on Github-Flavored Markdown.
Do not forget to commit your code! It automatically updates your profile page – the newly minted README is displayed above your pinned repositories. That’s it! You’ve just completed your very first iteration of your Github profile bio.