Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

105 lines (66 sloc) 2.455 kb

How to Write Documentation

The Basic Rules

Location

Everything goes in source/. Files end in .markdown and generate a matching .html file in output/.

Format

The basic format is Markdown. The output is generated by Jekyll and Maruku, which supports the features provided by PHP Markdown Extra.

NOTE: Markdown + ERB is supported (.markdown.erb), but should not be used unless absolutely necessary. Contributions in this format are tightly restricted.

Preamble

Every document must have a preamble. At the very least, this means a layout and a title:


layout: default

title: Language Tutorial

Replace the title with the title of the document you're adding.

If you forget these, your document will not be generated.

In practice, you should aim to have your documents have a title, summary paragraph, list of main points or accompanying references, and the separator. This makes a nice looking preamble section.

Something like:

Homer Simpson
=============

Homer Jay Simpson is a fictional main character in the animated
television series "The Simpsons" and father of the eponymous family.

He has 3 children:

* Bart
* Lisa
* Maggie

* * *

More Content
------------

More stuff down here.

Code

Code is indented from the left margin by four spaces, in normal markdown style.

We support Jekyll's Liquid Extensions for Code Highlighting.

The best code highlight style to use is Ruby. This presents Puppet code in a mostly accurate highlight.

Linking

Use absolute paths (eg, /guides/goo/bar.html) whenever possible; this makes moving documents less tedious.

Footnote-style linking is preferred.

Assets

Assets go in files/. During generation, this directory is copied to output/files/.

Layout

The layout is at source/_layouts/defaults.html.

Beyond adding important documents to the pretty "Docs Index" box, you shouldn't need to edit it.

Viewing Documentation

You need to generate the content and view the output/ directory.

At minimum, you probably need to do this:

$ sudo rake install
$ rake run

See the README for more details.

Jump to Line
Something went wrong with that request. Please try again.