How to create a README file for your GitHub profile, part 2: Markdown basics
GitHub repository with the final README.md file can be found at the end of the post.
Having a GitHub account in today’s world is a must-have for any software developer. In this series of posts, I’ll show you how to create a striking README.md file to attach to your GitHub profile. If you want to see an example of the final result, take a look at my GitHub profile!
If you’re new to Git, GitHub, or README.md files, make sure to check out the previous post of this series: How to create a README file for your GitHub profile, part 1: Intro to Git, GitHub, and README files.
Now, I’ll guide you through the basics of creating a Markdown file.
What is Markdown?
Wikipedia states that “Markdown is a lightweight markup language for creating formatted text using a plain-text editor. ... Markdown is widely used in blogging, instant messaging, online forums, collaborative software, documentation pages, and readme files.”
In summary, it’s a language used to write files using formatted text (like bold or italic characters, bulleted lists, numbered lists, headers, links, code, etc.). Markdown files end in .md (like README.md). I like to look at it as simplified HTML.
But enough theory. You’ll learn more with practice.
Create the repository to keep the README
If you don’t already have a GitHub account, please create one first. Once you have it, click on your profile picture at the top-right of the page and click on “Your repositories.”
Now click on the green “New” button.
This is important - you have to name your new repo exactly the same as your username. If you’re not sure what yours is, just click on your profile picture again, and you will see it after the “Signed in as …”. In my case, it’s “alexandramartinez”. You don’t have to add a description. Make sure to select “Public” and the “Add a README file” checkbox like in the screenshot below.
Click on “Create repository.” You now have a new repo with an (almost) empty README file. Click on the “edit” button on the right side of the README.md file.
This will bring you to the editor view. You also have a Preview tab in order to see the formatting of the file.
How to add headers in Markdown
Ok, from this point on, I’ll mainly show you the code and the explanations of the formatting. I trust you’ll use the “Edit file” and “Preview” tabs to make sure it looks as expected.
Replace your username with your own title. In my case, I wrote:
# Hi, I'm Alex!The hashtag character is used to specify headers. The single hashtag is the biggest one. You can use ##, ###, ####, and so on to specify what type of header you want to format (each smaller than the last one). In my README file, I’m just using the first title and the following header (H1 and H2). This is how my file looks so far, with all my headers and a brief introduction:
# Hi, I'm Alex!
I'm a Software Engineer who started creating content and is now a Developer Advocate!
## About