How to Write Documentation
The Basic Rules
Everything goes in
source/. Files end in
.markdown and generate a
.html file in
NOTE: Markdown + ERB is supported (
.markdown.erb), but should not be
used unless absolutely necessary. Contributions in this format are
Every document must have a preamble. At the very least, this means a layout and a title:
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.
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
The layout is at
Beyond adding important documents to the pretty "Docs Index" box, you shouldn't need to edit it.
You need to generate the content and view the
At minimum, you probably need to do this:
$ sudo rake install $ rake run
See the README for more details.