<oo>→<dh> Digital humanities

What is GitHub Pages?

GitHub Pages supports the publication of GitHub markdown and HTML files in a traditional web interface. GitHub already formats markdown pages during viewing, but it does that with limitations: the page is rendered inside a GitHub template (which contains information that is important for developers, but not for general readers) and there is no support for custom CSS. GitHub Pages does not support PHP or SSI, but it does provide it’s own scripting language. GitHub pages are built continuously; when you update a GitHub resource that is part of your GitHub Pages content, the GitHub Pages view is regenerated automatically. The site generation engine behind GitHub Pages, which converts markdown to HTML and interprets themes, includes, variables, plugins, etc., is Jekyll.

GitHub provides the following tutorial links:

• GitHub Pages basics
• GitHub Pages tutorial

You can learn more about Jekyll at their home page.

Our use of GitHub Pages

Our first encounter with GitHub Pages was in the context of Make your edition: models and methods for digital textual scholarship, an NEH-supported Institute in Advanced Topics in Digital Humanities. The GitHub repo for the Institute is at https://github.com/Pittsburgh-NEH-Institute/Institute-Materials-2017, and the GitHub Pages view is at https://pittsburgh-neh-institute.github.io/Institute-Materials-2017/.

There are several GitHub Pages tutorials available on the Web, but the configuration we eventually adopted draws on several of them, and we weren’t able to find all of the information we needed in one place. This is a summary of how we configured our site.

Enabling GitHub Pages

GitHub Pages is available for any GitHub repo, but it is not enabled by default. To enable it, go into Settings, scroll down, and do the following:

• Choose where to build your site from. We chose the Master branch for this repo; our new https://pittsburgh-neh-institute.github.io/Institute-Materials-2020/ is based on the alternative gh-pages branch of https://github.com/Pittsburgh-NEH-Institute/Institute-Materials-2020.
• Choose a theme, which will determine the default layout and decoration of your pages. You can customize the HTML template and the CSS later. We chose Slate.
• We ignored the Custom domain option.

_config.yml

Turning on GitHub Pages causes a file called _config.yml to be created in the top-level directory of your repo. Ours looks like:

theme: jekyll-theme-slate
title: NEH Institute materials
description: July 2017
baseurl: /Institute-Materials-2017

By default the only entry that will be is for the theme, and we added the other three. The optional title and description appear at the top of your GitHub pages as HTML <h1> and <h2> elements. GitHub Pages will find a default title if you don’t specify one (in our case, it used the <h1>-formatted first line of our main README.md file). You need to add the baseurl value, which should be the name of your repo preceded by a slash. Since our repo is at https://github.com/Pittsburgh-NEH-Institute/Institute-Materials-2017, our baseurl value is /Institute-Materials-2017. The baseurl value helps GitHub Pages identify links correctly.

Customizing the layout

Your theme comes with a default layout. If you want to customize it, create a top-level subdirectory called _layouts and follow the instructions for at Customizing your Jekyll theme's HTML layout. In our case, we wanted to include a navigation bar, using a GitHub Pages include. We did this by modifying the Header portion of the default layout by adding the highlighted line below:

<!-- HEADER -->
<div id="header_wrap" class="outer">
    <header class="inner">
      <a id="forkme_banner" href="{{ site.github.repository_url }}">View on GitHub</a>
      <h1 id="project_title">{{ site.title | default: site.github.repository_name }}</h1>
      <h2 id="project_tagline">{{ site.description | default: site.github.project_tagline }}</h2>
      {% if site.show_downloads %}
        <section id="downloads">
          <a class="zip_download_link" href="{{ site.github.zip_url }}">Download this project as a .zip file</a>
          <a class="tar_download_link" href="{{ site.github.tar_url }}">Download this project as a tar.gz file</a>
        </section>
      {% endif %}
      {% include nav.html %}
    </header>
</div>

Customizing the CSS

The theme comes with default CSS styling. If you want to customize it, follow the instructions at Customizing your Jekyll theme’s CSS. We wanted to add some right padding to some images, so we gave them a @class attribute value of rpad in the markdown (markdown doesn’t have HTML classes, but since it’s possible to include HTML with CSS, we switched into real HTML for that) and modified our CSS as follows:

---
---

@import "{{ site.theme }}";
.rpad {padding-right: 1em;}

Actually, markdown does have HTML classes, but they also show up as plain text in the default rendering in the GitHub repo, so including them in the markdown enhances the GitHub Pages functionality while impinging on the regular GitHub formatted view, which is why we don’t use them. See Jekyll tip: adding styling To HTML output for details.

Includes

GitHub Pages can include other files, similarly to SSI or PHP includes, but in this case the files to be included must be located in a top-level subdirectory called _includes. To include our navigation bar, we create the _includes subdirectory and then create nav.html inside it. Here is the text of our nav.html file:

<p style="text-align: center; background-color: white;">
  <a href="{{site.baseurl}}/">Home</a> |
  <a href="{{site.baseurl}}/admin/">Admin</a> | 
  <a href="{{site.baseurl}}/schedule/week_1/">Week 1</a> | 
  <a href="{{site.baseurl}}/schedule/week_2/">Week 2</a> | 
  <a href="{{site.baseurl}}/schedule/week_3/">Week 3</a> | 
  <a href="{{site.baseurl}}/general/">Misc</a>
</p>

We use the baserul value that we created in _config.yml to ensure that the links will find the files. The trailing slashes need to be there.

linking, yml prefixes. and permalink

GitHub pages follow links using relative paths, so if you have a link in your main README.md page like [Call](admin/call.md), when the GitHub Pages user clicks on the link, an HTMLified version of the call.md file in the admin subdirectory will be loaded. But navigation paths in GitHub pages are not able to use the .. notation to move upward in the DOM tree, which means that if you want to link to something that is not a sibling or descendant of the current page, you need to use an absolute path, which is what we’ve done in our navigation bar (and we would have needed absolute links in any case because the bar is included in pages at all levels of the hierarchy).

In order to make the main README.md pages in each major subdirectory accessible from the navigation bar, in addition to linking to them, we needed to create a yml prefix, which looks like:

---
---

You can set variables and include other page-specific metadata between the two triple-dashed lines, but the lines must be there, even if there is nothing between them. GitHub Pages does not default to index.md when you navigate to a subdirectory, so in order to make it load the main README.md file for that subdirectory automatically, we specified a permalink in the yml header. For example, for the README.md file inside our top-level admin subfolder, our yml header looks line:

---
permalink: /admin/
---

The leading and trailing slashes need to be there. The permalink value for our main README.md page is just /. The yml header information shows up in the regular formatted GitHub view of markdown files as a table at the top, which is sort of annoying, since it isn’t part of what we would consider page content.