Skip to main content

Generate Markdown text from templates.

Project description

RenderDown

Build Status

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.

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

How to Test

Run the following command to test:

$ pip install -r requirements.txt   # install dependencies
$ pip install -e .                  # to import in tests
$ python setup.py test              # run the test cases

License

MIT; see LICENSE for more information.

Project History

This project was created by Michael Wayne Goodman (@goodmami) and is now owned and maintained by Jeff Hung (@jeffhung).

Links

Project details


Release history Release notifications

This version

0.2.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for renderdown, version 0.2.0
Filename, size File type Python version Upload date Hashes
Filename, size renderdown-0.2.0.tar.gz (6.5 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page