GitHub Markdown Cheatsheet

When you post a project on GitHub, you want to put a README.md on the site to explain what you are trying to achieve. At first glance, the format for making it look nice is limited. Which is true, it is deliberately limited to make the use simple. You still have a good amount of freedom for your file. You may want pictures, screenshots come to mind, make headings and switch text style. These are just the most basic things you can do, and they are all standard Markdown. GitHub Flavoured Markdown is the same with a few extensions.

The standard Markdown

Markdown is a standard developed by John Gruber. The main goal with Markdown is to make the file possible to read even in pure text. If you want to look in a text-only editor, you should have an easy time reading it. This is very helpful for users of vim and similar. Note, and remember that this is a standard for changing text files. It is not replacing HTML. Instead, you use it to create HTML where it is useful. In the case of GitHub, they will format the Readme file on the site. As long as you follow the standard, you can feel certain it will look good.

Since GitHub has added just a few extensions, you should start by using a Markdown cheatsheet and go from there. Here is a list of the most common ones.

The lists can be nested by indenting any items you want to have nested.

Other extensions to regular Markdown, you have the code blocks extensions above. They are not always supported by services.

The table is very simple, but you need several rows to show it: Table:

GitHub Extensions.

GitHub has added a few extensions to make it simpler to handle links to other people and projects. Some of those are the tables mentioned earlier. The one that will help you the most is the auto-link extension. It creates a link on its own when you use it on GitHub.

Others are tables and Task list items. These are convenient for keeping track of your tasks in projects. The last one to mention is the Disallowed Raw HTML extension. With the help of this extension, some tags are filtered when rendering for HTML. These tags can cause strange effects when rendering to GitHub.

Ways to explore GitHub Markdown

If you find it confusing, you can also go to the GitHub page and use the built-in editor. When you use it, it will auto-complete some functions. This only works for issues, but you can use it to figure out some things, the emojis comes out as a list when you type a colon (:).

You can also find a project on GitHub that has great looking README file and clone it to your local drive. From there, you can explore the file using any editor you wish. For the big editors, Emacs and Vim, there is support for markdown through extensions.

If you are using vim, you can put in a syntax highlighting extension from GitHub, vim-markdown. This extension shows you that you have done the code correctly. To help you see how it looks when done, you can also get the live mark extension. With this, you can have a web server running, showing the result live as you type.

With Emacs, you have impatient-mode, live down-mode and Realtime-preview. They all show your resulting page in a browser while you type. The first requires less libraries than the latter but needs an extra code-snippet to run.

Conclusion

Even though markdown is a small and deliberately simple specification, it can be a little confusing to get started with. The best way to learn is to use a cheat sheet and write your Markdown document. You can update your README.md on GitHub, and you can get a lot of support from your editors’ built-in functions. As a side note, GitHub also supports emojis which you can add to your document. You can use the cheat sheet to find which ones they are.

Download Markdown-CheatSheetHere