Creating a Guide

Introduction to Jekyll

GitHub Pages sites run on Jekyll, a static site generater that allows us to use Markdown instead of (or in addition to) HTML. Your guide will live in a Markdown file in the _posts directory of the intrasite repository (in the gh-pages branch). Here, create a file in the following format: YYYY-MM-DD-title.md. At the top of the file, the front matter must be included. This is metadata that specifies the layout, author, and title of the post, as well as the category that the guide falls into and the logo that the site will use when creating a link to the guide. If you can’t find a nice looking image to use as the logo, use default.svg. The front matter is delimited by three dashes (no spaces between them) on the top and bottom. As an example, the front matter for this guide is as follows:

---
layout: post
author: Courtney McBeth
categories: ['Website']
logo: markdown_logo.png
title: Creating a Guide
---

You can also reference the other posts in this directory for examples. Note that the logo must be a file in the images directory. Below the front matter, you can begin your main content. For examples, see the other posts and the Markdown Cheatsheet. To publish your guide, simply push your changes to the gh-pages branch!

Formatting Code

One point of note is how to include blocks of code. Markdown supports code blocks, but a better solution is to use a JavaScript library. I have setup highlight.js for use on our site. To include a code block, follow these steps:

First, you must include the following three lines of html (exactly as they appear) underneath the front matter of your Markdown file.

<link rel="stylesheet" href="{{site.baseurl}}/css/code_styles/hybrid.css">
<script src="{{site.baseurl}}/js/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>

Now, wherever you want your code block to appear, include something like this:

<pre>
<code class="some_language_here">
<!-- your code here -->

</code>
</pre>

Replace the class name some_language_here with the name of the language you are using (something like “python”, “shell”, or “html”).

Formatting Tables

You might push your guide and find that something looks off. In this case, there are several ways to modify the formatting. For tables, I’ve provided a possible solution. Markdown allows you to add an annotation to some elements so that additional formatting can be applied. Try adding the post_table annotation as shown below.

{:.post_table}
| Wire      | Connection                           |
| --------- | ------------------------------------ |
| Red       | Ground                               |
| Yellow    | Power to wind direction sensor       |
| Green     | Wind direction output                |
| Black     | Wind speed contact closure to ground |

If there’s some element other than a table that you’d like to format, feel free to insert it in html (markdown allows html elements) and add a class or id of your choosing. You can apply your formatting in css/master.css.

Formatting Math

If you’d like to insert LaTeX-like math into your guide, you can use the MathJax library. Insert the following lines at the top of your file (beneath the front matter):

<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

Reference this demo for specifics on formatting. Remember to enclose your equations within <p> </p> tags so that it will be processed as HTML. For example, this code:

<p>
  \[ x = \frac{y}{\sqrt{z \pm w}} \]
</p>

turns out like this:

\[ x = \frac{y}{\sqrt{z \pm w}}. \]