How to Create a Github Profile README Using Markdown

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! 

Example

Here is an example using my Github profile: 

Code:

<img src="https://images.unsplash.com/photo-1444492417251-9c84a5fa18e0?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=975&h=300&q=80"/>
 
### Hi there 👋, I'm Christina Kopecky. I'm a web developer and technical writer. Welcome to my gh page! <br>
 
Resume:  [Christina Kopecky Resume](https://resume.christinakopecky.com) (PDF download)
 
🔭 *Currently working on*:  Articles that teach students and developers new-to-them technologies. Here are some examples of what I have been writing on: <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [React Components: Class vs. Functional](https://careerkarma.com/blog/react-components/)<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [Web Fundamentals: JavaScript Scopes and Closure](https://careerkarma.com/blog/javascript-closure/)<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [CSS Flexbox](https://careerkarma.com/blog/css-flexbox/)<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [MongoDB vs PostgreSQL: what to consider when choosing a database](https://www.educative.io/blog/mongodb-versus-postgresql-databases)<br>
 
🌱 *Currently Learning*: React-Native and Ruby<br>
🤔 *Looking for help*: I'm looking for help with trying to find my first software engineering job in this current job climate.<br>
💬 Ask me about: how to mentor students, creating a portfolio site for you, or assistance with an application you are working on. <br>
📫 How to reach me: <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [Email](christina@christinakopecky.com)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [Twitter](https://www.twitter.com/cmvnk)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [LinkedIn](https://www.linkedin.com/in/cmvnk)
 
😄 Pronouns: She/Her/Hers <br>
⚡ Fun facts:<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; :musical_note:  In my previous career I was a flutist and flute teacher. You can hear me play here: [Hypnosis by Ian Clarke](https://www.youtube.com/watch?v=6MiZszJjBIQ)<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; :fallen_leaf: My favorite season is fall :smile: <br>
 
 
<!--
**ckopecky/ckopecky** is a ✨ _special_ ✨ repository because its `README.md` (this file) appears on your GitHub profile.
 
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: ...
-->

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.