Making a website using GitHub pages
Previously, the easiest options have been either to either:
- Directly edit an HTML file and then use GitHub Pages
- Make a website in Markdown and render it using Couscous, a PHP-based Markdown to HTML converter
However, as of December 2016 GitHub will by default render Markdown using Jekyll when this feature is enabled in a GitHub repository (instructions here). You can specify the branch in the online repo settings; for documentation-only repos, it is probably easiest to just use the master branch.
Initializing the page
Enable jekyll in the project’s online settings. Either put this on the gh-pages or master branch. In practice, I find that the “Minima” theme works the best.
_config.yml to change the settings of the repo. For example, to get rid of the header
README.md will become the site’s
index.html. Internal links to other markdown pages will be automatically converted to links to the rendered pages
Changing the theme
If you change the Markdown theme using the GitHub web editor, you will need to synchronize your local copy with the theme template used in the remote. The safest way to do this is:
- Push all your content changes to the remote branch
- Edit the Jekyll theme/other web settings
In your local branch run
$ git pull
However, the best way to change formatting is to pick specify the Jekyll theme/other attributes with a local _config.yml file. This also allows you a little more control over your choice of theme. I particularly like the “minima” theme, which can be accessed by adding to your
_config.yml this line:
The default themes have various options that can be partly edited by changing the frontmatter of individual Markdown files (or all the defaults in the
Change URL if hosting through Google Sites
Register the GitHub domain as a redirect from your purchased Google Sites URL For specific subpages that you want to have a special link, for now the best option is to individually redirect a subdomain.
flowtrace.org ---> http://www.williamgilpin.github.io/flowtrace_docs/ gallery.flowtrace.org ---> http://www.williamgilpin.github.io/flowtrace_docs/gallery
Notes and Miscellaneous
After trying to customize, the page will not render, and checking the repo settings reveals a build error message “The value ‘nil’ was passed to a date-related filter that expects valid dates…”
- If you override the Jekyll defaults for GitHub pages, you need to at least specify a dummy date in your config defaults file
On Chrome, you can bypass the cached version of the page using Command + Shift + R. This is useful for previewing updates.
Be very, very careful when using a .gitignore. I tried to set mine to ignore all tilde (~) files created by my text editor, and the page formatting repeatedly failed.
Don’t mess around with baseURL in your
_config.yml file. This may cause the Jekyll theme not to render properly (see this GitHub issue thread)
I added a Google Analytics script using HTML, but it’s also possible to specify it as an attribute in the Markdown file. (see this StackExchange thread)