FIRSTwiki The FIRST Robotics encyclopedia

Style Guide (advanced)

This covers various things you can add to your Markdown content to make content more uniform and save you some typing.

Categories

It is often useful to have a set of pages that are associated together in a category, so that we can create automatically updated lists of those pages.

You can specify that a page belongs to one or more categories by adding a tags variable to the ‘front matter’ that is found at the beginning of most pages:

---
title: Page Title
tags: category1 category2
---

You can display a listing of all pages that match that category using this include on a page somewhere:

{% include by_tag collection=site.tech tag="category1" %}

The ‘collection’ parameter references the collection that the page is in (this is usually the topmost parent directory of the page). In this case the page is in the ‘tech’ collection

The ‘tag’ parameter names the specific tag that you want to create a list of

Redirect Pages

Sometimes pages get renamed, or there are multiple names for the same topic. In these cases, a redirect page can be created. The entire content of the page should look like this:

---
layout: redirect
redirect_to: new_page_name
---

Includes

We use jekyll’s include mechanism to provide standard commonly used templates that can be included on FIRSTwiki pages. Here is a list of the includes, and a description of when/where to use them.

Cleanup

{% include cleanup %}

Output

This article needs some cleanup. You can help FIRSTwiki by editing it.

Description

Displays a notice that this article is a bit messy and needs some love.

Historical

{% include historical %}

Output

The following information is outdated, but is retained for historical reasons

Description

Displays a notice that this section of an article contains information that is retained for historical reasons, and does not need to be updated. This is not the same as outdated information that needs to be updated. That should use the outdated-warning include instead.

Outdated warning

{% include outdated-warning %}

Output

The following information is most likely outdated. You can help FIRSTwiki by updating the information.

Description

Displays a notice that this section of an article contains information that while may be useful, is most likely outdated.

POV

{% include POV %}

Output

Description

Displays a notice that this article is a disputed and should be updated.

Stub

{% include stub %}

Output

This article is a stub. You can help FIRSTwiki by expanding it.

Description

Displays a notice that this article is a stub and should be updated.

Todo

{% include TODO %}

Output

This would be a great place to put some content! You can help FIRSTwiki by adding more information here.

Description

Display a notice that a specific section of a page needs some more work. This is different from a note that the entire page needs work; prefer the stub or cleanup includes in those cases.

{% include wikilink topic="Topic" %}

Output

Description

FIRSTwiki is not meant to replace something like Wikipedia, but rather it is meant to supplement it with FIRST-specific information. When you want to provide a pointer to a wikipedia page as the primary source of information, use this include. For normal references, use the same mechanism as any other external links.

Other

Because FIRSTwiki is a jekyll-based site, you can take advantage of any of the capabilities that jekyll offers. There are several places where FIRSTwiki takes advantage of these capabilities that are not documented here.

For more information aout jekyll, refer to their documentation at http://jekyllrb.com/docs/.