GitHub Pages
GitHub Pages is a Web service that allows the user to host a free website created from Markdown files.
Overview
If you already have experience with GitHub and need to host a website on the internet, you can directly use the GitHub Pages storage service.
It is worth mentioning that the pages hosted on GitHub Pages are simple pages, like pages in HTML, there is no server for you to run PHP, Python or Ruby and neither a database.
To host a website, just create a new repository, insert your Markdown formatted files and activate the GitHub Pages feature.
GitHub Pages is one of the tools with greater compatibility with Markdown using as base the static website generator Jekyll.
The tool also offers themes to the users so they don't have to start their sites from scratch.
Of course, you can create a website and format it using your own CSS.
Below, you can see a Web page built with one of the themes offered by GitHub Pages.
Just out of curiosity, GitHub Pages and GitHub use different Markdown processors. GitHub has its own Markdown processor while GitHub Pages uses jekyll-commonmark.
With this incongruence between Markdown processors, some formatting may appear differently in your README.md file.
The most notorious would be the use of emoticons, on GitHub website it would be rendered but on the website generated by GitHub Pages it would be not.
https://pages.github.com/ is the GitHub Pages official website.
GitHub Pages Markdown Support
In Table 1.1 the Markdown elements compatible with GitHub Pages are shown.
| Element | Support | Information |
|---|---|---|
| Titles | Yes | |
| Paragraphs | Yes | |
| Line breaks | Yes | |
| Bold | Yes | |
| Italic | Yes | |
| Blockquote | Yes | |
| Ordered lists | Yes | |
| Unordered lists | Yes | |
| Code | Yes | |
| Horizontal lines | Yes | |
| Links | Yes | |
| Images | Yes | |
| Tables | Yes | |
| Fenced code blocks | Yes | You can highlight the code block content but to do that it's necessary to check if the option syntax_highlighter: rouge is in the _config.yml configuration file, this option is located in the kramdown section. |
| Footnotes | Yes | |
| Title Id | Yes | |
| Definition lists | Yes | |
| Strikethrough | Yes | GitHub Pages provides support for both syntaxes, with two tildes ~~word~~ and one tilde ~word~. |
| Task lists | Yes | |
| Emoji (copy and paste) | Unknown | |
| Emoji (access codes) | Unknown | |
| automatic URL Link | Yes | |
| Disable automatic link from URL | Yes | |
| HTML | Yes |
Support for additional elements
Table 1.2 shows elements not so familiar to Markdown users that are supported by GitHub Pages.
| Element | Markdown | Output |
|---|---|---|
| Abbreviation | *[HTML]: Hyper Text Markup LanguageThe HTML specification is maintained by the W3C. |
The specification of HTML is maintained by the W3C |