Syntext

A lightweight, markdownish markup language for generating HTML.

Version 2.8.0

Tagged Blocks


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

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

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.

Although a block's content is determined solely by its indentation an optional end marker can be added to support syntax highlighting in editors which struggle with indentation-based syntax:

::: tag
    block content
    ...
::$

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

•   code

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

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
    This is a comment.

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

•   div

::: div
    This is a paragraph inside a div.

Inserts a <div> element. Can contain any kind of block-level content.

•   hr

::: hr :::

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

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

•   image, !image

::: image http://example.com/image.jpg
    [Optional alt text.]
    Optional image caption.

Inserts an <img> element. The first argument is used as the source url.

Classes, attributes, etc. are attached to the outermost element.

•   infobox

::: infobox .warning
    Careful now!

Creates an info box — a <div> element with the class infobox which can be styled appropriately using CSS.

::: link http://example.com/
    Link text or any other inline content.

Inserts a link. The first argument is used as the url.

•   quote

::: quote "Oscar Wilde"
    Work is the curse of the drinking classes.

Inserts a <blockquote> element. If a caption argument is provided it will follow the blockquote element wrapped in a div with the class .blockquote-caption.

•   span

::: span
    Spans can only contain inline content.

Inserts a <span> element. Can only contain inline content.

•   table

Indicates that the block contains a simple table literal:

::: table

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

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.