Skip to content
Find file
Fetching contributors…
Cannot retrieve contributors at this time
105 lines (66 sloc) 2.4 KB

How to Write Documentation

The Basic Rules


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


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.


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 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.


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

Footnote-style linking is preferred.


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


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.