GitHub Pages are the perfect way for geeks to create personal or project websites, blogs. GitHub uses Jekyll, a static site generator.
Install Jekyll if you want to preview the generated pages locally. Ruby and Gem are the only prerequisites.
gem install -v 0.11.0 jekyll
Optional: install Pygments if you want to test code syntax highlight locally. See the Jekyll Install page for details. It is recommended to use the same Jekyll version as GitHub if you want to push it.
Create the Basic Layout of Your Site
. ├── _layouts │ └── default.html ├── _posts │ └── 2011-11-11-hello-world.markdown └── index.markdown
default.html will hold the HTML code that wraps your content, e.g:
Fire up your favorite text editor, open
and create your first post in your favorite syntax (mine is Markdown). The
post file name must start with a properly formatted date.
Now you can run Jekyll locally:
jekyll --server --auto
Open http://localhost:4000/2011/11/11/hello-world.html and you should see the miracle.
It is useful to have an
index.html to list your posts, let’s create
Open http://localhost:4000/ and voilà! Now you can add posts, improve the layout and implement some nice design. The following pages are useful for learning more about the tools used:
- Jekyll README
- Jekyll’s YAML Front
Matter is the
page metadata between the
- Jekyll’s Template Data are the variables available in the pages.
- Learn to use Liquid, the ‘macro’ language of the pages, and Jekyll’s Liquid extensions.
- Learn Markdown or whatever markup syntax avaliable to Jekyll you prefer.
Push it to GitHub
Once you are happy with the newly created site, you can publish it to GitHub. Two options are available:
- User/organization pages:
myname.github.comrepository will be available at http://myname.github.com
- Project pages:
gh-pagesbranch will be available at http://myname.github.com/myproject
More instructions can be found at the GitHub Pages Introduction.
Tips and Tricks
If you are creating project pages, every url has to be prefixed with the project name, e.g:
It can even be made configurable:
_config.yml with the following content:
Override this with Jekyll’s
--base-url [url] command line switch locally if
you like so (e.g. to serve from the root).
Use HTML5 in Pages or Layouts
Maruku understands HTML5 tags. Add
this to your