Everything goes in source/. Files end in .markdown and generate a
matching .html file in output/.
The basic format is Markdown1. The output is generated by Maruku2, which supports the features provided by PHP Markdown Extra3.
There are a few additional extensions we've made.
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 title and a separator:
This is a Title
===============
* * *
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.
Snippets are denoted by the following syntax:
{SOMEWORDSINCAPS}
When encountering this, the generator will look in the snippets/
directory for a matching file; in this case, namely:
snippets/somewordsincaps.markdown
If found, it will replace the marker with that content.
WARNING: You can put snippets inside snippets. No pains are taken to protect against infinite recursion. So don't do that.
If you prepend a paragraph with INFO, NOTE, or WARNING, you get
a pretty colored box and icon.
Code is indented from the left margin by four spaces, in normal markdown style.
When possible, use Maruku's2 meta syntax to mark the format, as we'll be adding syntax highlighting in the future, ie:
file { "/etc/myfile.conf":
mode => 700,
# ...
}
{:puppet}
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/layout.html.erb.
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 output/ directory.
At minimum, you probably need to do this:
$ sudo rake install
$ rake run
See the README for more details.