GitHub will publish repositories containing markdown as web pages, automatically.
You’ll need to add this content:
---
---
A pair of lines with three dashes, to the top of each markdown file. This is how GitHub knows which markdown files to make into web pages.
Here’s why: https://jekyllrb.com/docs/frontmatter/ for the curious.
Let’s create a Github page:
%%writefile index.md
---
title: Github Pages Example
---
Mountains and Lakes in the UK
===================
Engerland is not very mountainous.
But has some tall hills, and maybe a mountain or two depending on your definition.
Overwriting index.md
and commit our change.
%%bash
git commit -am "Add github pages YAML frontmatter"
[master a19da7c] Add github pages YAML frontmatter
1 file changed, 6 insertions(+), 2 deletions(-)
GitHub creates github pages when you use a special named branch.
This is best used to create documentation for a program you write, but you can use it for anything.
os.chdir(working_dir)
%%bash
git checkout -b gh-pages
git push -uf origin gh-pages
Switched to a new branch ‘gh-pages’
To git@github.com:UCL/github-example.git
! [rejected] gh-pages -> gh-pages (non-fast-forward)
error: failed to push some refs to ‘git@github.com:UCL/github-example.git’
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: ‘git pull …’) before pushing again.
hint: See the ‘Note about fast-forwards’ in ‘git push –help’ for details.
The first time you do this, GitHub takes a few minutes to generate your pages.
The website will appear at http://username.github.io/repositoryname
, for example:
http://UCL.github.io/github-example/
You can use GitHub pages to make HTML layouts, here’s an example of how to do it: http://github.com/UCL/ucl-github-pages-example, and how it lookshttp://ucl.github.com/ucl-github-pages-example.