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.

Pages

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.

Buttons

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

buttons:
  - text: Home
    href: /
  - text: View on GitHub
    href: https://github.com/lapps/lapps.github.io/
  - 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:

buttons:
 - text: Edit on GitHub
 - href: https://github.com/lappsgrid-incubator/lappsgrid-incubator.github.io/edit/master/wiki.md
 - target: _blank

Navigation Menu

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.

---
nav:
  - 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.

---
nav:
  - FAQ
---

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

{% include nav.html %}

Dropdown Menus

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

menu:
 - 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.

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
nav:
 - edit

YAML

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 site.data.filename object.

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

- name: Alice
  homepage: http://www.example.com/alice
- name: Bob
  homepage: http://bob.example.com

The data can then be used with:

{% for person in site.data.people %}
1. [{{ person.name }}]({{ 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:

{{ site.top }}

HTML

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.
</div>

Will produce the following:

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.

CSS / SCSS

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:

• .note and .tip for <div> elements
• styling for the “Back to the top” links
• styles for the menus

Template

See the Template.md file for a starting point for wiki pages.

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

# Heading One

Put content here.

# Heading Two

More content.

# Sub-Heading

{{ site.top }}

Themes

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:

<html>
	<head>
		<title>{{ page.title }}</title>
	</head>
	<body>
		{{ content }}
	</body>
<body>

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:

<html>
	<head>
		<title>This is an example</title>
	</head>
	<body>
		<h1>Examples</h1>
		<ol>
			<li>list item one</li>
			<li>list item two</li>
		</ol>
	</body>
<body>

Available Themes

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

• cayman
• slate
• modernist

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

Templates

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:

buttons.html

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.

nav.html

Generates a simple navigation menu at the top of a page with links to anchor elements on the same page.

menu.html

Generated drop-down menus at the top of the page just under the header and above any navigation menu.

Scripts

./start

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

_scripts/restyle

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

./restyle slate cayman

_scripts/MakeIndex.groovy

Use this script to generate the site index (Contents.md).

groovy _script/MakeIndex.groovy > Contents.md

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.

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 Contents.md. Push the updated file to GitHub.

add a link to the top of the page.

Add {{ site.top }} to your markup file. The `site.top` 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>