31 March 2013

How to install Jekyll Bootstrap on GitHub Pages for your project?

Create a new gh-pages branch in your repository

git clone https://github.com/username/projectname.git
cd projectname/
git checkout --orphan gh-pages
git rm -rf .

Inject Jekyll Bootstrap into your local repository

cd ..
git clone https://github.com/plusjade/jekyll-bootstrap.git
cd jekyll-bootstrap/
rm -Rf .git
mv * ../projectname/.
mv .gitignore ../projectname/.
cd ..
rmdir jekyll-bootstrap/
cd projectname/

Customize Jekyll Bootstrap

rm -rf _posts/core-samples
vi _config.yml

You might want to modify the author :, title : and tagline: sections.

Modify your index page: vi index.md.

Jekyll accepts Markdown and HTML as input formats. You can even mix them in one file.

It then uses templates to render the final static pages, in the _site folder.

You can test locally your website, just by typing jekyll --server and then navigating to http://localhost:4000 with your favorite browser.

They are many other things that you can do with Jekyll and Bootstrap to create the best blog or website ever. Please refer to official documentations for more details.

Publish to GitHub Pages

Once you’re ready to publish the very first version of your website.

git add *
git add .gitignore
git commit -a-m "Initial commit"
git push origin gh-pages

Then it’s time to be patient, comb your unicorn or call your ex, because GitHub may take several minutes before “jekyllizing” your gh-pages branch.

Finally, your website should be online: http://username.github.com/projectname/

You can now start to update your website:

  • Add new pages: rake page name="about.md"

  • Add new posts: rake post title="Hello World"

  • Test you site locally and then push commits to your project’s gh-pages branch on GitHub.

DNS tricks

If you have a domain name you can even point it (or a subdomain of it) to your GitHub pages.

Entire domain pointing on GitHub Pages

In your registrar control panel, create or modify an A entry to make it point to GitHub Pages servers.

mydomain.org             A       204.232.175.78

In your gh-pages branch create a CNAME file containing the name of your domain: mydomain.org.

Point a subdomain to GitHub Pages

In your registrar control panel, create or modify an CNAME entry to make an alias of username.github.com.

mysubdomain.mydomain.org          CNAME   username.github.com

In your gh-pages branch create a CNAME file containing the name of your subdomain: mysubdomain.mydomain.org.

This even allows you to have multiple subdomains to point on the different GitHub Pages of your multiple projects:

  • from your registrar point of view the different CNAME entries will point to the same target (username.github.com)

  • but in your different gh-pages branches, the CNAME files won’t be identical because containing different subdomains (mysubdomain1.mydomain.org, mysubdomain2.mydomain.org…).

What about GitHub users or organizations?

If you want GitHub Pages to host websites linked with your GitHub user or organization, create a new repository named username.github.com and push your Jekyll Bootstrap contents into it instead of a gh-pages branch of an existing repository.

For more details on this DNS magic, refer to GitHub Pages help.