The present site is simple, with a style derived from JekyllBootstrap and Twitter Bootstrap with a particular theme. I’ll explain how to create a site with exactly this style. If you want something else, try the GitHub Pages automatic site generator, or look at the resources page.

These GitHub Pages sites are constructed by having a gh-pages branch of a GitHub repository, with specific files layed out in a specific way. To see the structure of such a repository, look at the repository for the present site.


The directories beginning with an underscore contain materials defining the basic layout and style for the site. If you build the site locally (for testing purposes), there will also be a _site/ directory containing the actual site (with Markdown files converted to html). You don’t want the _site/ directory in your repository, so include that in the .gitignore file.

The assets/ directory contains any non-Markdown materials for the site (e.g., images or example code). These files won’t be touched in the conversion but will be just copied over as-is.

The pages/ directory contains Markdown files that will become html pages on your site.

The _config.yml file contains all sorts of configuration parameters (some of which you’ll need to modify). The Rakefile contains instructions for the conversion; you won’t modify this file.

It’s best to always include and files. But you wouldn’t need these to be placed on the website; they’d just be viewed in the repository on GitHub. The _config.yml file contains a line sort of like the following (but listing a few more files), indicating files to not move to the final site.

exclude: ["", "Rakefile", ""]

Finally, is the Markdown version of the main page for your site.

The file and the Markdown files in pages/ (e.g., the present page) have a header with a particular form:

layout: page
title: simple site
tagline: Easy websites with GitHub Pages
description: Minimal tutorial on making a simple website with GitHub Pages

In the conversion of the site from Markdown to html, this bit says that the current file is to be converted with the “page” layout, and gives the title and the (optional) “tagline.” The “description:” part gets converted into <meta name="description" content="Minimal tutorial on..."> which, in principle, may be used in the results of google searches.

The rest is basically plain Markdown, though the present site is configured to use kramdown as the Markdown converter (via this line in the _config.yml file). Read about the kramdown syntax or just look at the quick reference.

Now go to the page about how to make an independent website.