Jekyll Github pages

Goal

To setup a website using github-pages, and to test it locally.

Reference Docs

• Setup github pages locally
• Setup github pages in master/docs folder
• Learn about Ruby Gems
• Learn about bundler

Traces and Notes

Installing github-pages (specific version of jekyll for github)

# Use github UI to create git repo 'site-jekyll'
git clone <site-url>
cd <site>
#not-needed, use docs -- git checkout -b gh-pages
# create Gemfile which installs jekyll
gem install bundler
bundle install
git add Gemfile Gemfile.lock

About github-pages

• Try github-pages --help
• Update github pages with gem update github-pages

Create and test the github jekyll site:

bundle exec jekyll _3.3.0_ docs
cd docs
# In docs, edit the Gemfile to use github-pages instead of jekyll. Change title and description if you like. 
bundle exec jekyll serve -H 0.0.0.0

Publish site online

The website is published automatically when a page is changed. This must be enabled on Github. This is the procedure in the github online UI:

• select the repo
• select ‘settings’ (in the repo menu on the far right)
• scroll down to ‘Github Pages’. Select as source ‘Master/docs’.

When happy, commit and push to publish

git status
git add .
git commit -am "publish as it is now"
git push

Notes

• bundle install failed:
  correction: do sudo apt install zlig1g-dev
• short note about gem and bundle:
  • bundle maintains specific dependencies for the specific project in file Gemfile.lock;
  • gem specifies dependencies more loosely, and provides an executable for many projects.
  • if you want to create an app, then you want to commit Gemfile.lock; otherwise not.