Naming conventions

You create files named (for example) template.html and content-for-name-goes-here.html. Poki merges those to create name-goes-here.html.

Callback CSS

Poki creates boxes with content in them. It renders these using

<div class="pokitoc">...</div>

<div class="pokipanel">...</div>

You can define this div-class to look however you want for your pageset. An example is here:


.pokinav {
  display:        inline-block;
  background:     #ffffff;
  border:         1;
  box-shadow:     0px 0px 3px 3px #c9c9c9;
  margin:         10px;
  padding-top:    10px;
  padding-bottom: 10px;
  padding-left:   10px;
  padding-right:  10px;
}

.pokitoc {
  display:        inline-block;
  border:         1px solid black;
  background:     #ffffff;
  box-shadow:     0px 0px 3px 3px #c9c9c9;
  margin:         10px;
  padding-top:    5px;
  padding-bottom: 5px;
  padding-left:   10px;
  padding-right:  10px;
}

.pokipanel {
  display:        inline-block;
  background:     #ffffff;
  box-shadow:     0px 0px 3px 3px #c9c9c9;
  margin:         10px;
  padding-top:    2px;
  padding-bottom: 2px;
  padding-left:   15px;
  padding-right:  15px;
}

Template-side markup

Here are some things you can put in your template.html:

POKI_PUT_AUTOGEN_DISCLAIMER_HERE: use this to place comments in the output files reminding anyone editing them that they were autogenerated, and how they got that way:
```


```
POKI_PUT_PAGE_LIST_HERE: use this to control placement of the navbar.
POKI_PUT_TITLE_HERE: use this to control placement of the page title from poki.cfg.
POKI_PUT_BODY_HERE: use this to control placement of the page body.

Content-side markup

POKI_PUT_TOC_HERE: use this to control placement of the table of contents. Note in particular that you only get a TOC if you ask for it this way. Also note that if you have
```
<h1>Section name</h1>
```
then two things will happen: one is that Poki will rewrite this to
```
<h1>Section name</h1><a id="Section name"/>
```
so that the TOC link can find it. The other is that the TOC link will be of the form
```
<a href="#Section name">Section name</a>
```
POKI_PUT_LINK_FOR_PAGE(name-of-other-page.html)HERE: In name-of-one-page.html simply put POKI_PUT_LINK_FOR_PAGE(name-of-other-page.html)HERE. Poki will replace that with a hyperlink to name-of-other-page.html, with link text taken from the page title in your poki.cfg.
POKI_INCLUDE_ESCAPED(file-name-goes-here)HERE: Include the contents of the specified file, wrapped by <pre> and </pre>, with & < > sent to & < >, respectively. Useful for including code snippets.
POKI_CARDIFY(single line of text here)HERE: Format single line of text the same way as POKI_INCLUDE_ESCAPED. Useful for including code snippets.
POKI_RUN_COMMAND{{shell command}}HERE: Run shell command and then format the command name and its output the same way as POKI_INCLUDE_ESCAPED. Useful for creating technical documents which match the current status of the software, without copy/paste errors or stale duplicative content. Example using POKI_RUN_COMMAND{{uptime}}HERE:
```
$ uptime
19:44  up 17 days,  6:58, 4 users, load averages: 2.37 2.00 1.80
```

poki.cfg

This pageset’s poki.cfg looks like this:

# Here is a comment
index.html                          About Poki
walkthrough.html                    Walkthrough
details.html                        Details # Here is another comment
setup.html                          Setup
contact.html                        Contact information
# Blank lines are ignored:

ext:http://github.com/johnkerl/poki GitHub repo

Simply put the page name on the left, and your desired title after that. Two special cases for the page name are:

sep:texthere Text here: Just writes the words “Text here” in the nav bar with no hyperlink. You can use this to separate one logical grouping of pages from another.
ext:urlhere Text here: Writes an external hyperlink to urlhere with the specified href “Text here”.

Limitations

Poki isn’t very smart — it’s just a few hundred lines of Ruby. I wrote it in about an hour to get the minimal set of features I wanted, although I’ve tweaked it a bit since then.

Everything that follows is true as of May 2015:

Lowercase your <h1>, <h2>, etc., or hack on poki to make it find these case-insensitively.
Place your <h1>, <h2> all the way to start of line. This how I differentiate section headers intended for the TOC from content about HTML.
Put only one POKI_... directive per line of your template or content files — or, again, hack on poki to handle multiple directives per line.
Please put POKI_CARDIFY(...)HERE POKI_INCLUDE_ESCAPED(...)HERE POKI_RUN_COMMAND{{...}}HERE on lines entirely by themselves.