How To Use This Site

0. Tone Guide

When writing updates for this site, keep your contributions brief, plain, and to-the-point.

At some point, somebody will be looking to this site for assistance, and it’ll be easier to find help if we keep our writing sparse. A little cheekiness is okay now and then, but this site should be defined by its helpfulness, not by its humor.

Keep your message clear and easy-to-understand. Too many developers let advanced vocabulary go unexplained. If you need to use an ambiguous term, like “endpoint,” give a definition for it with a tooltip.

Updating the Site

Every time you update the site, please do the following:

1. If you created a new page, set the status to draft. Otherwise, change the page status to revised.
2. Wrap your updates in a .diff div, so that the team can review it faster.
3. Update the revision info in the page block.
4. Update the header.html file if you’ve added a new page / changed the location of an existing page.
5. Notify the rest of the team about your update (could set up a notification in Slack for this).
6. After the team reviews your update and gives it the +1, change the status to resolved and remove the .diff div.

1. Local Setup

To begin, you’ll need to install these things:

1. Jekyll: run the command gem install jekyll from Terminal
2. Node.js and npm: download Node.js first, and check to make sure npm is up-to-date.
3. Install Bower locally by running the command: npm install -g bower.

We install Bower so that we can keep the Foundation framework updated, and Jekyll so that you can preview your edits locally. Next:

1. Download the site repo from Github
2. cd into the local repo, and run jekyll serve to compile updates locally before committing.

2. Page Setup

This site is written in Jekyll, which uses a combination of Markdown and static HTML files to display content. Start by assuming your page will be Markdown, unless you need to add a significant amount of custom markup for the specific page you’re working on.

Every page needs a configuration block:

Markdown

---
layout: page
title: How To Use This Site
permalink: /how-to-use-this-site/
status: draft
revisioncount: 1
lastedit: 10/20/15
initial: JHN
---

Notes

1. Layout: the current layouts are “default” and “page”
2. Title: the page title, used in the head and in the .post-header
3. Permalink: be sure to end it with a slash, or else Jekyll will try to download the file instead of display it.
4. Status: draft, revision, resolved. Draft for the initial write-up, revision for after we review it, resolved after we agree on it.
5. Revision info: every time you update a page past the initial draft, update the revision count, last edit date, and initial it.

When creating a new page, keep it grouped with other pages if necessary. Follow the naming convention “groupname-pagename.md;” e.g., the CSS Style Guide is titled “style-guides-css.md,”” so that it’ll be grouped next to other style guide pages when you’re editing the site.

2. Markdown

Add Classes to Markdown

Here's some content.
{: .class1 .class2}

<p class="class1 class2">Here's some content.</p>

Column Classes and Code Blocks

See the Kramdown syntax on HTML Blocks – HTML tags wrapped around Mardown content should have either a markdown="block" attribute, or a markdown="span" attribute.

Add syntax highlighting via a Pygments highlighting block.

<div class="row">
  <div class="medium-6 columns" markdown="block">
    ##### Left Column
    ~~~ html
    Fenced Code Block
    ~~~
  </div>
  <div class="medium-6 columns" markdown="block">
    ##### Right Column
    {% highlight html %}
    <div>Highlighted Block</div>
    {% endhighlight %}
  </div>
</div>

<div class="row">
  <div class="medium-6 columns" markdown="block">
    <h5>Left Column</h5>
    <pre><code class="language-html">
    Fenced Code Block
    </code></pre>
  </div>
  <div class="medium-6 columns" markdown="block">
    <h5>Right Column</h5>
    <pre><code class="language-html" data-lang="html">
    <span class="nt">&lt;div</span><span class="nt">&gt;</span>
      Highlighted Block
    <span class="nt">&lt;/div</span><span class="nt">&gt;</span>
    </code>
    </pre>
  </div>
</div>

Watch your tabs! Tab-indented markup might accidentally be converted to a code block. The easiest way to avoid this is to write code with a highlight tag.

Gists vs Code Blocks

Code blocks with the Pygments highlighting look better and laod faster than Gists, but Gists are a bit easier to share. Use your best judgement.