The Wiki

The LAPPS Grid wiki is just the GitHub Pages website for the LAPPS Grid organization. GitHub uses Jekyll to render the markdown files into static html files and if you have Jekyll installed locally it is possible to preview any local changes before pushing them to GitHub.

To install Jekyll.

gem install jekyll bundler  

To preview the wiki site run the following commands in the directory containing the wiki pages:

bundle exec jekyll serve --watch

Now open http://localhost:4000 in your web browser. The --watch parameter tells Jekyll to rebuild any files that change on disk.

Back to the top


Every GitHub Page consists of:

  1. some front matter
  2. some markdown

Front Matter

GitHub/Jekyll will not serve a page if it does not contain YAML front matter surrounded by triple dashes:

layout: default

If the front matter is missing Jekyll will ignore the file. The layout should always be set to default.

Back to the top


The navigation buttons that appear in the header are defined in the front matter:

  - text: Home
    href: /
  - text: View on GitHub
  - text: Site Index
    href: /Contents

The href may contain relative, absolute, or remote links. The value of the text field will appear as the text for the button. If no buttons are defined in the front matter a default set of buttons will be included. The default set of buttons is defined in the _includes/buttons.html template. If you do not want any buttons to appear in the header define buttons: none in the front matter.

It is also possible to specify a target if you would like the page to open in a new browser window/tab:

 - text: Edit on GitHub
 - href:
 - target: _blank
Back to the top

A simple navigation menu can be created at the top of a page by including a nav list in the front matter. Each item in the list will have a link generated where the href is derived by converting the label to lowercase and replacing spaces with dashes. This is (more or less) the way that Jekyll automatically generates anchors for header elements.

  - Menu One
# Menu One

If the menu label and heading are the same nothing else needs to be done. If the text you wish to use as the menu label does not match the header text simply create an anchor of your own.

  - FAQ

# <a name="faq"></a>Frequently Asked Questions

A navigation menu will be included by at the top of the page just under the header. However, it is also possible to include other navigation bars in the page by including the nav.html Liquid template

{% include nav.html %}

Back to the top

It is also possible to define drop-down menus that will appear at the bottom of the header.

 - Home: /
 - Edit: 
   - Cut: /edit/cut
   - Copy: /edit/copy
   - Paste: /edit/paste
 - Support:
   - Email: /support/email
   - Phone: /support/phone
   - Chat: /support/chat   

Drop down menus only support one level of sub-menus at this time.

Back to the top

HTML5 Notes

While it is possible to use the id attribute as the target of a an href attribute this can have several undesirable side-effects; namely a global variable in Javascript (which may or may not be what we want) and possible conflicts with ID values generated by Jekyll. Therefore it is recommend to use the name attribute when creating named anchors. Many browsers will also choke if the <a> tag does not have a closing </a> tag so avoid self closing tags.

<a id="dont-do-this"/>

<a name="do-this-instead"></a>

See this StackOverflow question for more discussion.

Edit on GitHub

It is possible to add “Edit” links to the buttons section or in the navigation menu. To add an edit button to the header of a page include edit: true in the front matter. To add an edit link to a navigation menu include edit in the list of navigation items.

edit: true
 - edit
You can use either uppercase Edit or lowercase edit and the case used in the front-matter will be the case used in the navigation menu.
Back to the top


Variables for use in templates or markdown can be defined in three places.

  1. The front matter. YAML included in the front matter will be available in the page object in the template or markup file.
  2. The _config.yml file. These variables will be accessible through the site object. This is how the Back to the top links are generated. See below.
  3. YAML files located in the _data directory. These variables will be available through the object.

For example, assume _data/people.yml contains the following:

- name: Alice
- name: Bob

The data can then be used with:

{% for person in %}
1. [{{ }}]({{ person.homepage }})
{% endfor %}

which will generate:

  1. Alice

  2. Bob

Back to the top

As was mentioned above the _config.yml file defines a variable named top that can be referenced to generate Back to the top links.

top: <a class='top' href='#top'>Back to the top</a>

Simply include the following where you would like the link to appear:

{{ }}


GFM (GitHub Flavored Markdown) does not support everything that is possible with HTML. In particular definition lists are not supported and tables without a heading row are impossible. Fortunately, GFM supports embedded HTML to do things that are not possible in markdown.

<div class="note">
    <em>Example</em><br/>The lapps.scss stylesheet defines a .note class that adds a border, adjusts the margins, and redefines the &lt;em> tag.

Will produce the following:

The lapps.scss stylesheet defines a .note class that adds a border, adjusts the margins, and restyles the <em> tag.
NOTE You **cannot** use markdown in a HTML element, you must use HTML for any styling. For example, notice that the word "cannot" above is wrapped in asterisks. The asterisks were not interpreted by the markdown processor and appear verbatim in the output.

It is important to ensure that all HTML is well formed. Any malformed HTML (unclosed tags etc.) WILL result in the page not rendering correctly.


Jekyll supports SASS stylesheets and any *.sass or *.scss files will be automatically be compiled into their *.css counterparts. The wiki defines several custom styles in the assets/css/lapps.scss file:

Back to the top


See the file for a starting point for wiki pages.

layout: default
 - text: Home
   href: /
 - text: Index
   href: /Contents
 - Heading One
 - Heading Two
 - Heading Three
 - home: /
 - edit: /Edit 
 - support:
   - phone: /support/phone
   - email: /support/email
   - chat: /support/chat

# Heading One

Put content here.

# Heading Two

More content.

# Sub-Heading

{{ }}

Back to the top


A Jekyll Theme is a Liquid template file stored in the _layouts directory. The variable {{ content }} in the template will be replaced by the HTML generated from the markdown.

For example, suppose we have the following in _layouts/example.html:

		<title>{{ page.title }}</title>
		{{ content }}

we can use this layout with the following:

layout: example
title: This is an example

# Examples

1. list item one
1. list item two

which will result in the following html being generated:

		<title>This is an example</title>
			<li>list item one</li>
			<li>list item two</li>

Available Themes

GitHub provides several default themes that can be used on GitHub Pages sites. Three of them are available in the _layouts directory:

To change the theme used by the LAPPS Grid wiki make a copy of the desired theme and rename it default.html.


A Liquid template is a snippet of HTML (plus the Liquid code) in the _includes directory that can be included in other pages/templates. Several templates are available can be used in the selected theme:

Creates buttons in the header for any buttons defined in the page's front matter. These buttons are intended to include links to other pages, including pages on other sites.
Generates a simple navigation menu at the top of a page with links to anchor elements on the same page.
Generated drop-down menus at the top of the page just under the header and above any navigation menu.



Starts the local Jekyll server. The web site will be available at http://localhost:4000


Changes the layout: for all .md files in the current directory add all subdirectories.

./restyle slate cayman
Note this script should not be required as all pages should use the default layout.


Use this script to generate the site index (

groovy _script/MakeIndex.groovy >

The script will walk the directory tree starting at the current directory and generate a markdown page with links to all the .md files found.

Back to the top

Frequently Asked Questions

How do I…

change themes?
  1. Delete _layouts/default.html
  2. Copy the desired theme to _layouts/default.html
The theme may require manual modification to make use of the buttons.html and menu.html templates located in the _includes directory.
update the site index?
Run the _scripts/MakeIndex.groovy script and redirect the output to Push the updated file to GitHub.
add a link to the top of the page.
Add {{ }} to your markup file. The `` variable is defined in _config.yml.
create notes with the border around them?
Create a <div> with the class note.
<div class="note">This will have a border. The margins will also be adjusted.</div>
Back to the top