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 relative paths when linking pages WITHIN a large document. Use absolute paths (e.g. /guides/goo/bar.html) when linking pages OUTSIDE the current document.
When linking from a PE manual to an upstream project manual, use the version of that upstream project that that PE version contains (e.g. PE 3.3 links to Puppet 3.6). In all other cases, use the "latest" alias.
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.
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.