GitHub Pages

Overview

Teaching: 10 min
Exercises: 5 min

Questions

• How can I host a website?

Objectives

• Learn how to host a static website with documentation or a blog on a Git Platform.

GitHub, offers hosting pages directly from a Git repository.

Creating a web page with GitHub pages

Let’s try out serving a small page on GitHub from within our planets repository.

First we need to activate the “Pages” functionality for this repository on GitHub:

1. go to the repository’s settings,
2. scroll down to “GitHub Pages”
3. in the dropdown select master branch / docs folder
4. click Save
5. we don’t use the Theme Chooser at this point.

Continuing in our planets repository directory open a new file _config.yml in the nano editor

$ nano _config.yml

and add the following content:

# _config.yml
# Jekyll configuration
name:  My Cool Page
title: My Cool Page
description: A Documentation Page created with Jekyll
theme: jekyll-theme-architect

Exit and save that file.

Next create a new file index.md

$ nano index.md

and add the following Markdown content:

<!-- index.md -->
# My Testing Docs Page

It Works! :-)

1. Have a `_config.yml` file setting a `title`, `name`, `description` and `theme`.
2. Add an `index.md` file with the landing page in Markdown.
3. Add more `*.md` files, e.g. `about.md`

Now we commit the changes and push them to GitHub:

$  git add _config.yml index.md
$  git commit -m "my first GitHub page"
$  git push origin master

Switch back to the browser and reload the settings page. Under the GitHub pages section you should now see the URL under which the site was published (https://<username>.github.io/planets/). Click on that link – et violà!

From the data inside the Jekyll configuration file _config.yml and landing page index.md in Markdown format, a website was build on the GitHub servers and is now available to be viewed by anyone.

Change the Jekyll theme

Go back to the repository’s settings and use the Theme Chooser to select a different theme.
Notice that this has generated a new commit. Use git pull origin to pull this change into your local repository.

Key Points

• GitHub offers a way hosting a website on their platform.

• The pages are stored in a Git repository.

• The pages are static in a sense that there are no server-side scripts or databases.

• GitHub builds pages from Markdown files with ‘Jekyll’

• Jekyll is executed whenever commits are pushed to the server.