How to set up and maintain Jekyll Documentation Theme

Jekyll_Doc_Theme.md

How to Setup and Maintain Jekyll Doc Theme

---

Table of Content

1. Install
2. Run Jekyll server locally (optional)
3. Maintain site
4. Miscellaneous items

---

1. Deploy theme on GitHub

1. Download ZIP archive of Jekyll Doc Theme from here and unzip it. Uncompressed version is named below documentation-theme-jekyll.
2. Create new GitHub repository online (here named myrepo), clone it, create gh-pages branch and move all content of doc theme into this branch. Additional details are available here.

clone https://github.com/tgirke/myrepo.git # clones new repos 
cd myrepo
git checkout -b gh-pages # creates gh-pages branch and switches to it 
git branch # lists branches and showes active one
mv ../documentation-theme-jekyll.* .
git add -A :/ # adds all content recursively to repository
git commit -am "some edits"; git push -u origin gh-pages # Commit to local and push to remote

1.2 URL of website

After the above steps the web site can be viewed in a Browser under the following URL:

https://tgirke.github.io/myrepo

2. Run Jekyll server locally (optional)

This is useful for debugging and checking changes to the site locally prior to committing them to GitHub.

2.1 Install/upgrade Ruby

If necessary install or upgrade Ruby. The follwoing upgrade method is from here.

sudo apt-add-repository ppa:brightbox/ruby-ng
sudo apt-get update
sudo apt-get install ruby2.2
sudo apt-get install ruby2.2-dev
ruby2.2 -v

If you have ruby >=2.3.x installed and only the ruby headers are missing (e.g. under Crouton with Ubuntu 16.04 LTE) then you need to install ruby-dev as follows.

sudo apt-get install ruby-all-dev

2.2 Install bundler to run Jekyll server with proper dependencies

After this follow Jekyll install instructions below. More details are here.

sudo gem install bundler # do only once
sudo bundle update # Creates Gemfile and Gemfile.lock containing dependency instructions for Jekyll

2.3 Run Jekyll server

# sudo gem install bundler # rerun this step if you re-cloned site
bundle exec jekyll serve # Runs Jekyll server with proper dependencies

After this you can view the site in a browser locally under this URL:

http://127.0.0.1:4000/

To kill the server, execute ctrl-c or run this command:

kill -9 $(ps aux | grep '[j]ekyll' | awk '{print $2}') # kills all jekyll processes

Note: when running the Jekyll server locally, the site is built under a _site directory in both the gh-pages and master branches containing all static *.html files of a current instance.

3. Maintain site

3.1 Archive previous class instance

To create a new instance for new quarter and archive the previous one, copy repository according to these instructions and name it by the date of previous year. This new copy will be archived version, while the current repos will become the offering for the new class offering. Alternatively, separate branches could be used for each year but this has various disadvantages (e.g. access control and github.io limitatons).

4. Miscellaneous items

...

Hi, great readme and article.