Skip to content

Latest commit

 

History

History
146 lines (85 loc) · 3.62 KB

STYLE.md

File metadata and controls

146 lines (85 loc) · 3.62 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.

We use Kramdown, with GFM codeblocks, and a few Kramdown related exceptions introduced with {: } such as class names for specific formatting of columns and notes.

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 }

In-page table of contents

All pages have tables of contents generated automatically from H2 and H3

To remove the TOC from a page add no_toc: true to the frontmatter.

Note, warnings and blocks

We use the blockquote symbol > for general purpose notes and warnings.

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

Screencapture gifs

  1. Run a build (or whatever you are trying to capture),
  2. Capture it with licecap.
  3. Save the gif in images/