What is GitHub Pages?

GitHub Pages are free static web sites hosted directly from your GitHub repository. Using standard technologies like YAML and Markdown, anyone can build and maintain a site in minutes.

Suppose you want to set up a basic web site to share information about the project you’re working on. It might be a personal site, like as resume or portfolio. Or it might be a professional site, like a user guide or developer reference. With GitHub Pages, you can spin the site up in minutes and enable anyone with a basic understanding of Markdown to contribute to it. You also get all the benefits of GitHub for source control, including branches and pull requests.

In this module, you learn how to set up and use GitHub Pages to host both personal and professional websites.

Learning objectives

In this module, you will:

  • Enable GitHub Pages
  • Choose a theme with Jekyll
  • Use YAML front matter
  • Customize your site
  • Create and edit blog posts

Prerequisites

  • A GitHub account
  • The ability to navigate and edit files in GitHub

 

What is GitHub Pages?

Here, we discuss the process of creating and maintaining a GitHub Pages web site.

GitHub Pages are static sites hosted directly from your GitHub repository. But they’re more than just a collection of static files. By making use of site generation technologies like Jekyll and Liquid, developers define dynamic templates that are processed into complete static web sites. Every time a change is committed to the source branch associated with the site, it is re-generated using the latest updates and automatically published to the target URL.

Learn more about Publishing sources for GitHub Pages sites

 

Enabling GitHub Pages

The first step in using GitHub Pages is to enable it from your repository’s Settings tab. You can opt to use the master branch, or specify the docs folder within it. If you ever want to disable GitHub Pages, you can do so here.

enabling-github-pages

Choosing a theme with Jekyll

Jekyll is the static site generator used by GitHub to build your web site from the contents of your repository. In addition to providing great content convenience, it also conforms to a standard design convention. This style standardization allows for swappable themes, which you can select from the GitHub Pages configuration.

choosing-jekyll-theme

There are a variety of themes provided by GitHub. There is also an array of commercial and open source themes available from the Jekyll community.

jekyll-themes

Learn more about Jekyll Themes .

 

Using YAML front matter

The term front matter refers to YAML metadata that prepends the content of a file. For Jekyll, this includes generator instructions to indicate the layout style of a Markdown page (post, page, and so on). It may also include page metadata, such as the document title, or page content variables, such as a blog post’s author.

Below is a simple example that would use the post layout. This assumes there is a _layouts/post.html file that defines the container HTML. Other layout options may be offered by adding their respective HTML files in the _layouts folder.

Learn more about Front Matter .

Customizing your site

Once your site is up and running, you can customize details about your site via _config.yml. This file includes virtually all site-wide configuration options, including site metadata, navigation menus, theme colors, compiler options, and more.

Learn more about _config.yml Configuration .

Creating and editing content

Creating and editing pages on your site follows the standard GitHub experience. The files you use for your GitHub Pages web site enjoy all of the same benefits as other files in your GitHub repository, so you can edit them with any tool, create and merge branches, and link with issues or pull requests.

In addition to Markdown and HTML, Jekyll supports the Liquid template language syntax. Liquid provides the ability for users to dynamically insert variables and basic logic flow constructs into their content files. When compiled, the final product is standard HTML.

The example below shows a combination of for looping and variable insertion.

<ul>
  {% for post in site.posts %}
    <li>
      <h2><a href="{{ post.url }}">{{ post.title }}</a></h2>
      {{ post.excerpt }}
    </li>
  {% endfor %}
</ul>

Learn more about Liquid template language .

Working with blog posts

Despite not having a database to work with, Jekyll still supports the concept of blogging using a specific convention: _posts/2020-06-25-blog-post-name.md. As you can likely infer, all blog posts are stored in the _posts folder and use the date and name convention as shown. During compilation, Jekyll processes the files in this folder to produce a list of HTML blog posts.

The example below illustrates the structure of a simple blog post best reddit hosting 2020. It includes metadata for subtitle, tags, and comments, which may or may not be supported by the theme you choose.