Syntext supports an 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
    ...
::: end

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. Automatically escapes the HTML syntax characters <, >, and &.

This tag 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.

•   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.

• If the first line of the block's content is wrapped in square brackets it will be treated as the image's alt text.
• If a caption is provided, it will be wrapped in a <figcaption> element and the image and caption together will be wrapped in a <figure> element.
• If the !image tag is used, the image will be wrapped in a link to itself.

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

::: 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 <p> element with the class .blockquote-caption.

•   raw

::: raw
    This content will be passed through in its raw state.

Content inside a raw tag will be passed through in its raw state without any further processing.

•   table

Indicates that the block contains a table:

::: 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.

Note that you can't use the | symbol inside table literals — use the HTML escape code | instead.