Loyc

Language of your choice

How to put a site on GitHub

28 Jun 2018

GitHub has made it very easy to get started. If you already have a repo that you want to add web site for, just create a docs folder in the repo and start adding .md (Markdown) files to it; in particular index.md will be recognized as the home page. Then you can select a theme and view your pages as explained here. Links to other markdown files will automatically be converted to html links (for example if you write [link](file.md), it becomes <a href="file.html">link</a>.) You can also write content pages in HTML, but it is rarely necessary. It is possible to insert bits of HTML in your Markdown code if necessary (and Markdown in your HTML).

Then, if you want a custom theme like you see on this site, my TypeScript/React Primer is a good example:

---
layout: "default"
---

<main>
{{ content }}
</main>

Then the “page” layout is the same as the “default” layout (i.e. default.html) except that the content is placed within a main element. If you want to have more than one layout (style of page), but you want all pages to share some code, then the code that all pages share should go in default.html, and code that not all pages share should go in page.html or another layout file.

Having multiple layouts is not the only way (or even the best way) to customize pages, though, as we can see by looking at the site’s default.html file:

<!DOCTYPE html>
<html>
{% include head.html %}
<body>
{% include navbar.html %}
{{ content }}
{% if page.toc %}
{% include table-of-contents.html %}
{% endif %}
{% include google-analytics.html %}
</body>
</html>

This demonstrates two important features:

  1. Use {% include %} to insert code snippets from the _includes folder. For example head.html contains the <head> element for all pages on the site, and google-analytics.html connects to Google Analytics so I can find out if I have any visitors (however, GitHub itself now gathers its own statistics).
  2. Use {% if %} to insert code conditionally. table-of-contents.html adds a table of contents, but it is only included on pages with the toc: true option. In order to add the toc: true option you need to add something called front matter at the top of each page with a table of contents. Front matter starts and ends with ---, like this:
---
layout: "page"
toc: true
tagline: "This is another option"
---

### The page's content appears below the front matter ###

All features of GitHub Pages are provided by a software package called Jekyll, and the pages you write are actually Jekyll templates. Jekyll provides access to the options in front matter via Jekyll’s page object. For example

{% if page.toc %}stuff{% endif %}

inserts stuff if there is a toc option, and {{ page.tagline }} inserts the contents of the tagline string (if any) into the page. Options in the front matter can have any name you want; only a few names (like layout) are recognized by Jekyll itself. Generally, quotes around options are optional unless the option contains certain punctuation characters.

You can also put custom options in _config.yml which are accessible through Jekyll’s site object. For example, the google-analytics.html snippet inserts the google_analytics option into itself using {{ site.google_analytics }}. All the options on the Primer site are custom options, although the show_downloads is used only by GitHub themes (not my custom site) and the theme option is recognized by GitHub itself. In addition, there are some options you can put in _config.yml that are recognized by Jekyll.

Now that I’ve told you all this, you should be able to understand completely how the Primer site works.

Other tips

Possibly Related Posts