GitHub Pages is a service that turns Markdown files into a website and hosts them for free on the internet. If you know how to use GitHub and you need to create a simple webpage, you can’t do better than GitHub Pages. Just create a new repository on GitHub, commit the Markdown files, and enable the GitHub Pages feature.

GitHub Pages uses the Jekyll static site generator to create your website, and the Markdown support is excellent. You can pick one of GitHub’s pre-made themes for your website, use a Jekyll theme, or use your own custom CSS. Shown below is a sample webpage using one of GitHub’s pre-made themes.

Example of GitHub Pages websites

Confusingly, GitHub Pages renders Markdown differently than GitHub does. GitHub uses its own Markdown processor; GitHub Pages uses jekyll-commonmark. This means your README.md file will look different on GitHub’s website than on your GitHub Pages website. For example, emoji are rendered on GitHub’s website, but not on websites generated using GitHub Pages.

GitHub Pages Markdown Support

GitHub Pages provides support for the following Markdown elements.

Element Support Notes
Headings Yes
Paragraphs Yes
Line Breaks Yes
Bold Yes
Italic Yes
Blockquotes Yes
Ordered Lists Yes
Unordered Lists Yes
Code Yes
Horizontal Rules Yes
Links Yes
Images Yes
Tables Yes
Fenced Code Blocks Yes
Syntax Highlighting Yes Make sure that syntax_highlighter: rouge is in the kramdown section of the _config.yml file.
Footnotes Yes
Heading IDs Yes
Definition Lists Yes
Strikethrough Yes You can use two tildes (~~word~~) or one tilde (~word~) — both work.
Task Lists Yes
Emoji (copy and paste) Unknown
Emoji (shortcodes) Unknown
Highlight No
Subscript No
Superscript No
Automatic URL Linking Yes
Disabling Automatic URL Linking Yes
HTML Yes

Support for Additional Syntax Elements

As an added bonus, GitHub Pages provides support for several obscure elements.

Element Markdown Rendered Output
Abbreviation *[HTML]: Hyper Text Markup Language
The HTML specification is maintained by the W3C.
The HTML specification is maintained by the W3C.

See Also