GitHub Pages are great but wouldn't you like to be able to use .md files, instead of having to provide HTML, and have those files render like they do in GitHub README's etc?
The following covers how to do this. To see the kind of results you can achive, click here to see this README served via GitHub Pages.
Install RVM as per their instructions:
$ sudo gpg2 --keyserver hkp://pool.sks-keyservers.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
$ curl -sSL https://get.rvm.io | bash -s stable --ruby --ignore-dotfiles
I added --ruby
for the default version or Ruby and --ignore-dotfiles
as otherwise it completely spams a surprising array of dot file.
Then all you need to add to your ~/.bashrc
is:
# Add RVM to PATH for scripting.
export PATH=$HOME/.rvm/bin:$PATH
# Load RVM into a shell session *as a function*.
source $HOME/.rvm/scripts/rvm
Open a new terminal to pull in these changes.
Install Jekyll (as per the Jekyll installation instructions:
$ gem install jekyll bundler
Then make a directory for your experiments, this will not be the root for your GitHub pages site but rather its parent:
$ mdkir experiment
$ cd experiment
Then roughly following the details from GitHub docs:
$ bundle init
$ echo '' >> Gemfile
$ echo 'gem "jekyll", "~> 3.9.0"' >> Gemfile
Adjust 3.9.0
to match the version currently specified in https://pages.github.com/versions/ and then:
$ bundle install
Now we'll create the subdirectory containing the actual GitHub pages site:
$ bundle exec jekyll new my-gh-pages-site
$ cd my-gh-pages-site
Now edit the new Gemfile
that's been created here:
$ vi Gemfile
Delete the gem "jekyll"
line and uncomment the gem "github-pages"
line but add in a version so you end up with something like this:
gem "github-pages", "~> 209", group: :jekyll_plugins
The , "~> 209"
is the added-in bit and the version, here 209
, again comes from https://pages.github.com/versions/
Now install everything and serve the canned initial content:
$ bundle install
$ bundle exec jekyll serve
Code highlighting is on by default but there's no default CSS, to create it:
$ mkdir css
$ bundle exec rougify style github > css/syntax.css
First delete the canned initial content:
$ rm -r about.md index.md _posts
And create some Jekyll specific subdirectories:
$ mkdir _layouts _includes
And copy _layouts/default.html
into _layouts
and _includes/anchor_links.html
into _includes
.
Note that _layouts/default.html
depends on Sindre Sorhus's github-markdown-css to achieve the GitHub Markdown style.
By default smart-quotes are enable - which isn't the default on GitHub. So to disable this:
$ echo '' >> _config.yml
$ echo 'kramdown:' >> _config.yml
$ echo ' smart_quotes: ["apos", "apos", "quot", "quot"]' >> _config.yml
The Site settings
block in _config.yml
contains various values:
twitter_username
andgithub_username
can be removedtitle
,email
anddescription
appear to be mandatory but can be left with their default canned values.- Only the
baseurl
andurl
entries are really important - we'll come back to them later.
Now you're ready to go - just take any GitHub markdown page and save it as index.md
, e.g. take the raw markdown for this page.
Now all you need to change is to add what's called a front matter section at the top of the file:
---
layout: default
title: My example page
---
The layout
line tells Jekyll to use the default.html
layout file that we set up above. And the title
line sets the value used for the page's <title>
tag.
Now we're ready to serve it locally:
$ bundle exec jekyll serve
Open the link http://127.0.0.1:4000/ in your browser to see the result.
Now you're ready to get things served from GitHub pages.
Create an empty repository on GitHub, e.g. with the name my-gh-pages-site
.
Edit the _config.yml
file and:
- Set the
url
value tohttps://username.github.io
, replacingusername
with your GitHub username, e.g.george-hawkins
in my case. - Set the
baseurl
to your new repository's name preceded by/
, e.g./my-gh-pages-site
.
Now all your work to git:
$ git init
$ git add .
$ git commit -m 'Initial import'
Now follow the GitHub instructions for pushing an existing repository.
Then go to Settings for your repository, scroll down to the GitHub Pages section and save your main branch as the branch to be used as the source for your GitHub Pages site.
Note: previously, you had to create a gh-pages
branch but now you can specify any branch using this setting.
It should then tell you the link you can use to access your pages once they're published, it'll be of the form:
https://username.github.io/my-gh-pages-site
You can also get here via the Environments link on the main page of your repository. The Environments page will show you when your pages have been deployed and provides a View deployment button to view them.