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:
nl2br argument can be added to any block to turn on newline-to-linebreak mode for all nested content.
::: 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
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
>>> html = syntext.render(text, pygmentize=True)
::: 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 This is a paragraph inside a div.
<div> element. Can contain any kind of block-level content.
::: hr :::
Inserts a horizontal rule. Any number of dashes can be used in place of the
hr tag, e.g.
::: ------ :::
::: image http://example.com/image.jpg [Optional alt text.] Optional image caption.
<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
!imagetag is used, the image will be wrapped in a link to itself.
Classes, attributes, etc. are attached to the outermost element.
::: 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 "Oscar Wilde" Work is the curse of the drinking classes.
<blockquote> element. If a caption argument is provided it will follow the blockquote element wrapped in a div with the class
::: span Spans can only contain inline content.
<span> element. Can only contain inline content.
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
Attributes specified in the block header will be applied to the