How to Host Static Markdown/Web pages using Github Pages

Photo by Hal Gatewood on Unsplash

Github Pages allow you to host static markdown/web pages (HTML and JS) for free. You only need a few steps to have a website up and running.

I will show you how to build such a website using a course website as an example: https://harrywang.github.io/misy331/.

Step 1. Create an empty repo with basic information (you can leave .gitignore and license empty as the default setting):

Then, you will have a repo with a default README.md file as follows:

Step 2. Enable Github Pages: got to settings and scroll down to Github Pages section.

We choose master branch as the source of the website (you can also use docs folder, which you need to create and put all statics files there), choose a theme (you will be asked to edit the README.md, just accept the default content and commit as shown in the screenshots below):

Choose a theme:

Use the default README.md:

Now, the website is ready at https://harrywang.github.io/misy467/ showing the README.md file:

Step 3. Customize the header of the website, e.g., how to change the default title “misy467”, which is the name of the repo to something else. Github pages are based on jekyll, which uses the _config.yml to configure the site themes. You can find Github pages default themes at https://github.com/pages-themes.

Click and directly edit the file on Github:

I chose the cayman theme, whose official _config.yml is at https://github.com/pages-themes/cayman/blob/master/_config.yml, which shows how to customize the title, description, etc.

You can find other additional settings you can add to the configuration file, e.g., check out this example. Once we change the title and description as follows and commit the change:

The website will be updated in a minute or two to look like:

Step 4. Add different contents, such as images, html and js files, anchor links in Markdown, etc.

You can choose to use Github web interface to upload files and edit files. I prefer editing them locally and push to publish.

$ git clone https://github.com/harrywang/misy467.git
$ cd misy467/
# adding file and links
$ git add .
$ git commit -am 'added files and links'
$ git push

I added an HTML file and a JS file to demonstrate how you can host static webpages: Floating Ribbon using p5.js by Kjetil Midtgarden Golid.

The only tricky part for me is adding anchor links in Markdown. For example, I want to add a “Back to Top” link at the end of the page. The key here is: when you specify headings in markdown using # (or multple # in a row denote smaller heading sizes), an anchor is automatically created once you push the file to Github.

For example, I have two headings on top in README.md:

This is how you get the anchor: go to https://github.com/harrywang/misy467 and find the heading, click the interlock icon, and check the anchor in the URL of the browser: `#misy467-machine-learning-for-business-spring-2020` — essentially, all letters in the heading are changed to lowercase and spaces are replaced by dashes. When the heading is long and contains special spaces and symbols — my approach introduced here is really handy.

Then, you specify the anchor as follows in the Markdown file:

That’s it! Cheers!