Markdown regions

A region is a block of Remark text, together with the type of an html-element to wrap the block in.

Remark extends Markdown to support regions.

Defining regions

A region is defined by starting a line with !!!, and then writing a start-tag of an html-element. This begins a block whose content is denoted by indentation — exactly as with list items.

Content type

The content-type can be set through the remark-content attribute. The possible values are:

remark: The content is interpreted as Remark; the default.
remark-no-p: The content is interpreted as Remark, without wrapping first-level paragraphs into <p> elements.
text: The content is interpreted as raw text, embedded directly into html.

Examples

Content as Remark

!!! <div class = "test">
    This is in the region.

    This is too.

    * All nested notation is contained in the region, no matter how complex.
    * Another list item.

This is in the region.

This is too.

All nested notation is contained in the region, no matter how complex.
Another list item.

Content as Remark without first-level `<p>` elements

!!! <div class = "test" remark-content = "remark-no-p">
    This is in the region.

    This is too.

    * All nested notation is contained in the region, no matter how complex.
    * Another list item.

This is in the region. This is too.

All nested notation is contained in the region, no matter how complex.
Another list item.

Content as text

!!! <div class = "test" remark-content = "text">
    This is in the region.

    This is too.

    * All nested notation is contained in the region, no matter how complex.
    * Another list item.

This is in the region. This is too. * All nested notation is contained in the region, no matter how complex. * Another list item.

Uses

The region extension provides a robust way to wrap content into html-elements. In particular, the region extension allows Remark to wrap content in <div> elements, so that they can be styled via CSS.

History

The region extension was written because, in April 2015, Python Markdown had problems interleaving Markdown and html. While this worked reasonably well in old versions of Python Markdown, it did not work anymore in newer versions. We solved this by extending Python Markdown with regions. The !!! notation was chosen because the admonition extension already used it.

Files

Markdown region extension

MarkdownRegion.py