Jekyll
From charlesreid1
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.)