Syntext

A lightweight, markdownish markup language for generating HTML.

Version 2.0.0

Tagged Blocks


Syntext supports indentation-based tagged-block syntax for custom elements:

::: tag [arguments] [.class] [#id] [&attr] [attr="value"]
    block content
    ...
::: end

A block header can contain a single ID, any number of classes, and any number of named attributes. Block syntax also allows for one or more arguments to be supplied (how these are interpreted depends on the tag).

Boolean attributes can be specified using an & symbol, e.g. &checked. Attributes with values can be specified without quotes as long as the value does not contain spaces.

A block's tag determines how its content is processed. In general blocks can be nested to any depth and can contain any block-level content.

Note that a block's content is determined soley by its indentation; the ::: end tag is optional and can be used to enable syntax highlighting in editors which may otherwise struggle with indentation-based syntax.

Trailing colons in the header line are optional:

::: hr :::

is equivalent to:

::: hr

A nl2lb / nl2br argument can be added to any block to turn on newline-to-linebreak mode for all nested content.

Tag Reference

•   alertbox

::: alertbox .warning
    Careful now!
::: end

Creates an alert box — a <div> element with the class alertbox which can be styled appropriately using CSS. Standard type-classes are info, warning, and error.

•   code

::: code python
    def hello():
        print('hello world')
::: end

Wraps a code sample in <pre> tags. Accepts an optional argument specifying the language of the code.

If a language is specified then a lang-<language> class and a data-lang="<language>" attribute are added to the <pre> element.

If a language is specified and the Pygments package is installed then syntax highlighting can be applied to the code sample. This feature is turned off by default but can be enabled by supplying a pygmentize=True keyword argument to the render() function:

>>> html = syntext.render(text, pygmentize=True)

•   comment

::: comment
    Comment text.
::: end

Creates a HTML comment. The block's content is not processed any further but is included in the output in its raw state.

•   hr

::: hr :::

Inserts a horizontal rule. Any number of dashes can be used in place of the hr tag, e.g.

::: ------ :::

•   image

::: image http://example.com/image.jpg
    Alt text for the image.
::: end

Inserts an image element. The block's content is used as the image's alt text.

•   quote

::: quote
    Work is the curse of the drinking classes.
::: end

Inserts a blockquote element.

•   table

Indicates that the block contains a simple table literal:

::: table

    foo | bar | baz
    ---------------
    aaa | bbb | ccc
    ddd | eee | fff
    ---------------
    foo | bar | baz

::: end

Header and footer lines are optional. All three tables below are valid:

foo | bar | baz
---------------
aaa | bbb | ccc      aaa | bbb | ccc      aaa | bbb | ccc
ddd | eee | fff      ddd | eee | fff      ddd | eee | fff
                     ---------------
                     foo | bar | baz

Note that all the tables above can be 'boxed' with decorative outer lines of pipes and dashes, e.g.:

---------------      -------------------
foo | bar | baz      | foo | bar | baz |
---------------      -------------------
aaa | bbb | ccc      | aaa | bbb | ccc |
ddd | eee | fff      | ddd | eee | fff |
---------------      -------------------

Column alignment can be specified using colons as below:

default | left | center | right
------- | :--- | :----: | ----:
 aaaaa  |  bb  |  cccc  |  ddd
 eeeee  |  ff  |  gggg  |  hhh

Cells in the left column above receive the class left, cells in the center column receive the class center, and cells in the right column receive the class right.

Attributes specified in the block header will be applied to the <table> element.