Skip to content

Latest commit

 

History

History
136 lines (80 loc) · 3.04 KB

STYLE.md

File metadata and controls

136 lines (80 loc) · 3.04 KB
Raw

Travis CI documentation style guide

Markdown and structure

We're planning to lint the Markdown with Coala.io and the MarkdownBear.

We'll be using a subset (TBD) of the full list of checks.

Headings

For historical reasons, the top level heading in Jekyll markdown files is level 2 (##) not level 1 (#).

We use ATX style headings, and do not use the optional closing hashes:

## This is an H2

### This is an H3

#### This is an H4

We do not use underline style headings:

Do not use this style heading
=============================

Lists

If you have long lists you can wrap them into 2 (.column-2) or 3 (.column-3) columns using one of the follow CSS classes after your list item:

* long list item 1
* long list item 2
{: .column-2 }

TOC

Add a table of contents to a page with the following HTML snippet:

<div id="toc"></div>

Beta features

Mark all beta features with a specially formatted note. Both the > BETA and the {: .beta} are required.

BETA Awesome new feature that might not be enabled and is subject to change. {: .beta}

Alpha features

Mark all alpha features with a specially formatted note. Both the > ALPHA and the {: alpha} are required.

ALPHA Awesome new feature that might explode for extra fun. {: .alpha}

GUI

Make sure all references to items in a GUI match the case of the UI, and are marked with asterisks.

Links

Make sure all links have titles:

The [link][example1] in the text

[example1]: http://www.example.com  "Example URL"

or

The [link](http://www.example.com "Example URL") in the text

When linking internal pages, use absolute paths and trailing slashes: /user/languages/c/. You can link to headings, remember to remove special characters, for example:

To link to "##Node.js Page" use #nodejs-page.

Code Inline

All function names, filenames, etc should be marked with back-ticks.

If you're talking about applications or services, only the actual command should be marked as code, not the name of the service:

  • Start the PostgreSQL database by running psql.

Blockquotes / Notes / Warnings

As we have no use for blockquotes we use > to indicate notes and warnings:

> Note this important info!

Code blocks

Code blocks should be fenced with triple back-ticks "```" and named according to prism.js for syntax highlighting.

your code here

You can also set the filename for a code block by adding a Kramdown attribute after it:

This code is in .travis.yml

{: data-file=".travis.yml"}

Common misspellings and words to avoid

  • Always refer to Travis CI and never to Travis.

Images