RenderDown

Generate Markdown text from templates; that is, the result of rendering is Markdown text, not HTML. This is useful for generating documents published on a Markdown platform like GitHub Wikis.

Archive Notice

This repository is no longer maintained and has been archived, but the project continues with Jeff Hung (@jeffhung) as the new owner at https://github.com/jeffhung/RenderDown.

The remainder of the original README is kept below for posterity:

Usage

The simplest way to use RenderDown is to invoke it from the commandline:

renderdown.py TEMPLATE [--assign KEY=VALUE] [--outdir OUTDIR]

The required TEMPLATE argument is the path to a template file. Simple variables may be passed to the template with the --assign option. If the --outdir option is set, multi-file documents can be created, written to files in the output directory; if unset, the multiple pages are appended together and printed to stdout.

RenderDown can also be used as a library. The API.md file (generated using RenderDown and CartogrAPI) is a reference of RenderDown's API.

Templates

Templates are rendered with Mako. A doc variable is added to the namespace of all templates (see API.md for a description of the functions on doc). For example, if mytemp.mako is a template defined as follows:

# ${title}

Here are two bullet points:
${ doc.listitem("the first point") }
${ doc.listitem("note how wrapped lines\nare indented") }

${ doc.blockquote(
    "the same is true for blockquotes, except the > character is\n"
    "repeated on the wrapped lines.")
}

The the following call the RenderDown will render the template:

$ python renderdown.py example.md --assign title="Hello World"
# Hello World

Here are two bullet points:
* the first point
* note how wrapped lines
  are indented

> the same is true for blockquotes, except the > character is
> repeated on the wrapped lines.

The original use case for rendering Markdown is for publishing Python API documentation on GitHub Wikis, so the default templates target that platform.

The templates are defined for rendering packages, modules, classes, methods, and functions in a fairly generic way (inspired by documentation), but they can be reconfigured and specialized for individual projects.

Requirements

• Python 3.3+
• Mako

License

MIT; see LICENSE for more information.

Links

• Mako - templating engine

• D3.js's wiki - provided aesthetic inspiration for the wiki organization
• CartogrAPI - used to map out Python APIs
• Related Software:
  • doc2md
  • pdoc
  • Sphinx AutoAPI