Creating or Editing Documents

Creating a new document on the Arctos Handbook

You can do this either online on Github, or locally via a copy of the repo on your local computer (check out https://desktop.github.com/ ).

The Arctos Handbook is a Github Pages site rendered with Jekyll. For you, the editor, this means a few things:

All pages must live in a directory prefaced by _, such as _documentation
The very first thing on all pages must be YAML-compliant Front Matter
All pages must be written Markdown and and with the extension .markdown

We'll take these one at a time.

Where files live

On the back end of things, Jekyll treats directories with an underscore specially, but what's important to us is that all the directories that aren't special reserved names for the Jekyll engine become a "collection" for us, and a bunch of things happen automagically.

At the time of this writing, the only three directories documentation should be placed in are:

_documentation
_how_to
_resources

From within those directories, you can create a document (with whichever editor you'd like on your desktop, such as Atom, or via the "Create New File" button on Github) and get going. Remember to give your page the .markdown extension when naming it! The extension will automatically place the web editor and most local clients in the right edit mode to assist you.

What should I call my file?

All "How-to Guide" titles should start with "How to .." to distinguish tutorials from other Arctos documentation. Keep titles short and avoid punctuation or special characters (e.g., commas, colons, dashes, slashes, etc.) because the page title is used to format the URL.

I'm not sure where to put it

There are three kinds of content on the Arctos Handbook site:

Documentation, which describes specific data tables and/or types and defines data fields
"How-to Guides," which provide step-by-step instructions on how to do specific tasks in Arctos.
Resources, which you probably don't need to deal with

If you're still unsure where to place your documentation, ask!

Front Matter

the Jekyll documentation says it all:

The front matter is where Jekyll starts to get really cool. Any file that contains a YAML front matter block will be processed by Jekyll as a special file. The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines. Here is a basic example:
---
layout: post
title: Blogging Like a Hacker
---
Between these triple-dashed lines, you can set predefined variables (see below for a reference) or even create custom ones of your own. These variables will then be available to you to access using Liquid tags both further down in the file and also in any layouts or includes that the page or post in question relies on.

For us, the "you should almost always use" required parameters are:

---
title: TITLE HERE
layout: default_toc
---

The Arctos Handbook supports a few other Front Matter attributes. We also support author and date as an attribute, that, when present, show on the rendered page. An example that (as of this writing) is live on the Handbook site is:

---
title: Agents
layout: default_toc
author: ArctosDB
date: 2016-12-01
---

As an important note, if you do not include front matter on your page, the page will fail to compile, and will return a 404 Page Not Found error.

Markdown

Markdown is a "content-first" method of writing that directly translates to HTML without all the awkward tags. Github has a great quick writeup on it, but there are longer, nitty-grittier writeups on the web, too. The important things to remember are:

All paragraphs must have a blank space between them, eg,
```
blah blah

blah blah new paragraph
```

This is also true when transitioning paragraph types, such as code blocks or blockquotes.

Numbered and bulleted lists are generated automatically. Just start with 1. and every subsequent number will iterate (regardless of actual numerical progression, so 1, 1, 1 will become 1, 2, 3). Bullets can be a single asterisk or a dash.
Table-of-Contents entries are generated at headers. Headers are created by leading with one or more #. For example:

# Page title

This is a page about stuff and things

## First subheading

This is actually a really interesting topic.

### Sub-subheading

You see, ....

## Second subheading

Note that simply emphasized text (via *emphasized text*) nor bold text (via **bold text**) will generate either a table of contents entry or an HTML anchor to link to. Do not simply use bold text for sections!!

Wrapping up

Once you've saved your document, wait about one minute, and it'll be live!

It'll show up in search, but not in the page indices. If you're comfortable editing HTML directly, you can insert it into the appropriate index page (eg, for a page in _documentation, the _documentation/index.html file), or otherwise ask [email protected] or [email protected] to take care of it for you.

General notes

Titles

DO NOT EDIT an exisiting title because that will change the URL and thus affect linked pages.

Add a Table

In the page where you want to insert a table, follow the guide for Organizing Data into Tables in Github

Add Images

Give the image a URL: In a new tab, go to the documentation-wiki uploads folder, and click the "upload files" button.
- If you want to use the same tab, be sure to commit your progress, first.
Drag and drop the image or browse your computer for the image(s) and click the "commit changes" button.
Click on the desired image to preview it
Click on the "Download" button to get the raw URL. If the URL does not begin with https://raw.githubusercontent.com, the link will not work. Copy this URL to your clipboard.
Go to back to the page where you want to add the image, and click on the image icon above the text box. Insert the URL. Only the URL (not the image) will show up in the text box. In raw Markdown, you can specify an image with ![](URL_OF_IMAGE_HERE).
Hit the preview button to ensure you've correctly included the image
Commit your changes