Quick start

To get up and running with the default configuration of Piglet + reStructuredText:

pip install pages

pages --template layout.html --output build/ src/

For markdown, or to use another templating system, install the relevant extras hook, eg:

pip install pages[markdown,jinja2]

Examples

Select individual files to render:

pages --template layout.html -p1 --output=build/ src/index.md src/page1.md

Select a different template for a file:

pages --template layout.html -p1 --output=build/ src/ src/stats.json:report.html

Read the list of files to render from stdin:

find src/ -type f -name \*md | pages --template layout.html -p1 --output=build/

Select a different templating system:

pages --render-with jinja2 --template layout.html --output=build/ src/

Load additional data into the template context:

# Inline JSON
pages --template layout.html --context '{"foo": "bar"}' src/

# a JSON file
pages --template layout.html --context data.json  src/

# JSON loaded from a remote API
pages --template layout.html --context <(curl -s 'wttr.in/?format=j1') src/

# A python module
pages --template layout.html --context myproject.somemodule:avariable src/

# A python script
pages --template layout.html --context somevars.py src/

Path stripping

If you supply a directory to pages, it will render all the files inside that directory, stripping off the directory name. For example given a file at src/index.rst, this:

pages -t layout.html -o build/ src/

will produce this:

build/index.html

It will not strip the prefix of individually named files, so this:

pages -t layout.html -o build/ src/index.rst

will produce this:

build/src/index.html

Use -p <n>/--strip <n> to tell pages to remove one or more levels of path prefix. -p 1 will strip off one level of prefix, higher values will strip off more. -p 0 will leave the path unmodified.

Note that -p/--strip is only used for sources listed by full path names.

Rendering markdown

Markdown sources are processed using Python-Markdown with the “extra” and “meta” extensions loaded.

The template will be called with the following context variables:

{
    "html": ...,  # Content rendered as HTML
    "meta": ...,  # Parsed metadata
}

Rendering reStructuredText

reStructuredText sources make the following context variables available to the template:

{
  "title": ...              # Document title
  "meta": ...               # Key-value pairs from top level field lists
  "html": ...               # Rendered html body (incl. the title heading)
  "html_without_title": ... # As above, but without the title heading
  "parts": ...              # Parts dict as returned by the docutils writer
}