EDIT

This content has been completely altered since this initial posting, this is current as of Dec 2016

Purpose

Create a website with static content using markdown

Required software

See github_pages, you will need the following

Rather than having this software on my local machine I will use a docker container

Workflow

  • Create a github repository named pmcgrath.github.com (pmcgrath.github.io for newer accounts)
  • Clone github repository
  • Initialise jekyll content, see below
  • Run docker container serving jekyll content
  • Run the following in a loop until you are happy with the content
    • Edit content locally
    • View content in browser @ http://localhost:4000/
  • Push content to github

Docker usage

  • I have a docker image so that I can create and edit content locally and view it before I push to github
  • I do not need any of the required software on my local machine
  • To build an image you will need the following files
  • To build the image run the following bash command (Will need sudo prefix if user is not in the docker group)
docker image build -t pmcgrath/github-pages:1.0 .
  • To Run an instance of the docker image which watches for changes while editing, run an instance using
docker container run --rm -it --name github-pages -p 4000:4000 --volume $(pwd):/src pmcgrath/github-pages:1.0

Initialise jekyll content

  • Use the following bash command within the empty cloned repository to create the initial content
docker container run --rm -it --name github-pages --rm -v $(pwd):/src pmcgrath/github-pages:1.0 ruby -S jekyll new .
  • Edit the settings in the _config.yml file, changing the values appropriately
  • Use redcarpet markdown engine so we can use fenced code blocks, add the following to the _config.yml file
    • markdown: redcarpet # So we can use fences code blocks
  • Use permalinks for the links, so we just use the title for the urls, add the following to the _config.yml file
    • permalink: /:title # So title alone is used for the link

Create blog posts

  • Add a file to the _posts directory, you can copy the default post created when the jekyll content was initialised

Jekyll notes

  • Converts mardown content to static html content
  • Places the static version in the _site directory, can do so manually using the build command
  • Can serve content by running a web server listening on port 4000
  • Can be instructed to watch for content changes, which will result in re-generating the static content
  • Changes to the _config.yml will require restarting the container

Notes