Today we are happy to announce the very first version of our Jetstrap Documentation site running on GitHub Pages using Jekyll as the site generator. If you don’t know about us, Jetstrap makes it super easy to build Twitter Bootstrap interfaces and designs (try it, it’s free).
Since our tool has a lot of little features, we’ve had a lot of requests for better documentation and tutorials. I wanted to build something that was easy to maintain, “open” so others could collaborate and submit content, and fast. GitHub Pages is perfect for that.
Getting started with GitHub pages is always a bit of a pain. I forget how to push content to it, what URL to access the site with, how to set up a CNAME so we can use docs.jetstrap.com to access the site, what branch to use, etc.
Hopefully this tutorial gets you up and running fast on GitHub Pages.
Getting Started – Create the Repo
To start, we’ll need a normal github repo. If you are building a site for your user account, you should follow the yourname.github.com naming scheme for your repository. If you are creating a page for a project, you can use whatever naming scheme you want. I wanted this docs page to be a separate project, so I named mine jetstrap-docs.
Creating the repo is the same as any other: just visit https://github.com/new, pick your organization (or keep it as yourself), and create it.
Clone the repo locally, and check out a new branch called gh-pages or master if using user pages. You are now ready for the next step.
GitHub Pages Config
GitHub Pages for Projects works by hosting the gh-pages branch of your repo as a static site at the URL yourname.github.com/repo-name, or yourorganization.github.com/repo-name.
If you picked the User naming scheme, GitHub instead hosts the master branch of your repo at yourname.github.com.
If you want to set up a CNAME for a custom domain, it’s as easy as creating a CNAME file in your repository and putting in the CNAME you will use. For example, I put docs.jetstrap.com into our CNAME file and pushed it to the gh-pages branch.
Then, set up your DNS host to be a CNAME from your desired site to the root of your organization or project. This part is confusing, but in our example, we made a CNAME from docs.jetstrap.com to driftyco.github.com. Imagine GitHub looks at your repos and checks for the CNAME entry to display the proper repo matching that CNAME in your user/org account.
We use DNSimple for our DNS host which is super fast. I could test that the CNAME worked almost immediately.
What is with all the damn CNAME’s!?
Jekyll
Now that you have you repository set up, it’s time to create an initial structure for Jekyll.
If you haven’t used Jekyll before, it’s a static-site generator that builds a static version of your site with dynamic features. For example, you can create a base layout that all pages inherit from to reduce duplicated code. This means you get incredibly fast load times since it’s all static content, but you can take advantage of a lot of dynamic “backend” templating features you are used to in other languages.
To setup our initial Jekyll config, we create a _config.yml file. Check out ours for reference. The most important field in there is the permalink field, which specifies what URLs will be used to access content. I haven’t dug into the other possible values, so you might want to tweak some of them.
Next, make a directory called _layouts. This will store our base template layout so all pages can have the same look and feel. Inside of that folder, create a file called default.html and add your base HTML to it (see ours). The most important value in this template is the {{content}} directive, which will include the content from any page that inherits this page.
Next, create an index.html file that inherits from this layout. It’s as easy as adding a header with some meta data:
In this example we’ve also added a variable called “title” which we can access in our layout template to update the <title> tag in our HTML by adding the {{page.title}} directive, but this isn’t necessary.
Test it!
Testing with Jekyll is simple. First, if you haven’t installed it yet, follow the installation instructions or just do gem install jekyll from the command line.
Jekyll lets you run a local server and test your site out. To do that, run jekyll --server --auto. This will build your site, watch for changes, and start a server that is accessible at http://localhost:4000/. Feel free to make tweaks to your site and Jekyll will see the update and rebuild the site.
Hello, World
When you are ready to show the world all your hard work, just push to github and you are done!
You can now visit your site by accessing the CNAME you set, or by visiting yourname.github.com/repo-name, or yourorganization.github.com/repo-name.
Jekyll is really great, and hosting on GitHub is pretty much the best of every kind of world. Fast, convenient, cheap, and collaborative.
What about you? Any luck setting up Jekyll for a static site? Need help with anything?