Jekyll

Okay, here's what I did:

The repository I was trying to create a website for was called cantera-book

Used jekyll-base https://github.com/charlesreid1/jekyll-base to create base structure for a jekyll website, and put it in my repository in jekyll directory

In the jekyll directory I created a site called _site by cloning the gh-pages branch of cantera-book

(if you don't have one, do the git branch --orphan gh-pages thing)

Then when you run

jekyll build

to build the site in the _site directory, it will deploy the site to your new local version of the gh-pages branch of the repository.

When you like the changes, you can do

cd _sources
git push origin gh-pages

Jekyll for Github Project Page

My goal was to create a content-based, not a blog-based, Jekyll site to host a pile of Markdown pages organized into sections and subsections, turned into a nice-looking HTML site.

This was waaaay more convoluted than I think it should be.

I found a Jekyll pre-made site design that was intended for precisely what I described - embedding posts by section and subsection, in more of a book format, on Github, and forked it: https://github.com/charlesreid1/jekyll-base

What You Get

What you end up with, using jekyll-base, is really cool: a workflow that allows you to have a deployable Jekyll site, that you can tuck into the repository in its own directory, that will deploy a set of static pages to the gh-pages branch of your repository (which is where all the github pages content goes).

Here's how you do it.

The Workflow

First, check out jekyll-base:

git clone https://github.com/charlesreid1/jekyll-base 

Now check out your project:

git clone https://github.com/charlesreid1/cantera-book book
cd book

And copy the jekyll-base into the directory in your repository where you'll keep your Jekyll site's source. I'll call it something wildly outrageous, like "jekyll".

mkdir jekyll/
cp ../jekyll-base/* jekyll/.

Now the trick to making this workflow hang together: check out a copy of your gh-pages branch inside the jekyll folder. From our project directory, we:

cd jekyll/
git clone -b gh-pages http://github.com/charlesreid1/cantera-book _site

The reason we check out the gh-pages branch to _site is because when we run

jekyll build

we get all the static content built in _site - conveniently modifying the gh-branches repo in-place. When we're ready for the site changes to go live, we do this:

cd cantera-book/jekyll/_site/
git add .
git commit -am "Updating site content"
git push origin gh-pages

And if you're ready to push any changes to your Jekyll, you do:

cd cantera-book/jekyll/
git add .
git commit -am "Updating Jekyll"
git push 

Jekyll Layouts

If you want to install new layouts, you just put stuff in the _layouts directory. The _includes directory, which is optional, may include templates like a header and footer, etc.

You can also add Rakefiles to do things like turn LESS into CSS, but that gets beyond what jekyll-base is intended to do (other themes, like Jeyll Theme: The Minimum, will include a basic Rakefile that you can modify if you want a Rakefile with your site).

The layouts can also be modified with respect to what information they need from the Markdown headers. For example, one layout may require a date, while another layout may not.

This all ties in with how you can use Jekyll to do things like what jekyll-base is trying to do - make nestable sections and subsections and posts that live in those subsections.

(More on all this later.)