Djot syntax reference

Inline syntax

Precedence

Most inline syntax is defined by opening and closing delimiters that surround inline content, defining it as emphasized, or as link text, for example. The basic principle governing “precedence” for inline containers is that the first opener that gets closed takes precedence. Containers can’t overlap, so once an opener gets closed, any potential openers between the opener and the closer get marked as regular text and can no longer open inline syntax. For example, in

_This is *regular_ not strong* emphasis
<p><em>This is *regular</em> not strong* emphasis</p>

the regular emphasis opened by the first _ gets closed by the second _, at which point the first * is no longer eligible to open strong emphasis. But in

*This is _strong* not regular_ emphasis
<p><strong>This is _strong</strong> not regular_ emphasis</p>

it goes just the opposite way.

Similarly,

[Link *](url)*
<p><a href="url">Link *</a>*</p>

contains a link, while

*Emphasis [*](url)
<p><strong>Emphasis [</strong>](url)</p>

does not (because the strong emphasis closes over the [ delimiter).

Although overlapping containers are ruled out, nested containers are fine:

_This is *strong within* regular emphasis_
<p><em>This is <strong>strong within</strong> regular emphasis</em></p>

In cases of ambiguity, { and } may be used to mark delimiters as openers or closers. Thus {_ behaves like _ but can only open emphasis, while _} behaves like _ but can only close emphasis:

{_Emphasized_}
_}not emphasized{_
<p><em>Emphasized</em></p>
<p>_}not emphasized{_</p>

Ordinary text

Anything that isn’t given a special meaning is parsed as literal text.

All ASCII punctuation characters (even those that have no special meaning in djot) may be backslash-escaped. Thus, \* includes a literal * character. Backslashes before characters other than ASCII punctuation characters are just treated as literal backslashes, with the following exceptions:

  • Backslash before a space is parsed as a nonbreaking space.
  • Backslash before a newline is parsed as a hard line break.

Image

Images work just like links, but have a ! prefixed. As with links, both inline and reference variants are possible.

![picture of a cat](cat.jpg)

![picture of a cat][cat]

![cat][]

[cat]: feline.jpg
<p><img alt="picture of a cat" src="cat.jpg"></p>
<p><img alt="picture of a cat" src="feline.jpg"></p>
<p><img alt="cat" src="feline.jpg"></p>

Verbatim

Verbatim content begins with a string of consecutive backtick characters (`) and ends with an equal-lengthed string of consecutive backtick characters.

``Verbatim with a backtick` character``
`Verbatim with three backticks ``` character`
<p><code>Verbatim with a backtick` character</code>
<code>Verbatim with three backticks ``` character</code></p>

Material between the backticks is treated as verbatim text (backslash escapes don’t work there).

If the content starts or ends with a backtick character, a single space is removed between the opening or closing backticks and the content.

`` `foo` ``
<p><code>`foo`</code></p>

If the text to be parsed as inline ends before a closing backtick string is encountered, the verbatim text extends to the end.

`foo bar
<p><code>foo bar</code></p>

Emphasis/strong

Emphasized inline content is delimited by _ characters. Strong emphasis is delimited by * characters.

_emphasized text_

*strong emphasis*
<p><em>emphasized text</em></p>
<p><strong>strong emphasis</strong></p>

A _ or * can open emphasis only if it is not directly followed by whitespace. It can close emphasis only if it is not directly preceded by whitespace, and only if there are some characters besides the delimiter character between the opener and the closer.

_ Not emphasized (spaces). _

___ (not an emphasized `_` character)
<p>_ Not emphasized (spaces). _</p>
<p>___ (not an emphasized <code>_</code> character)</p>

Emphasis can be nested:

__emphasis inside_ emphasis_
<p><em><em>emphasis inside</em> emphasis</em></p>

Curly braces may be used to force interpretation of a _ or * either as an opener or as a closer.

{_ this is emphasized, despite the spaces! _}
<p><em> this is emphasized, despite the spaces! </em></p>

Highlighted

Inline content between {= and =} will be treated as highlighted text (in HTML, <mark>). Note that the { and } are mandatory.

This is {=highlighted text=}.
<p>This is <mark>highlighted text</mark>.</p>

Super/subscript

Superscript is delimited by ^ characters, subscript by ~.

H~2~O and djot^TM^
<p>H<sub>2</sub>O and djot<sup>TM</sup></p>

Curly braces may be used, but are not required:

H{~one two buckle my shoe~}O
<p>H<sub>one two buckle my shoe</sub>O</p>

Insert/delete

To mark inline text as inserted, use {+ and +}. To mark it as deleted, use {- and -}. The { and } are mandatory.

My boss is {-mean-}{+nice+}.
<p>My boss is <del>mean</del><ins>nice</ins>.</p>

Smart punctuation

Straight double quotes (") and single quotes (') are parsed as curly quotes. Djot is pretty good about figuring out from context which direction of quote is needed.

"Hello," said the spider.
"'Shelob' is my name."
<p>&ldquo;Hello,&rdquo; said the spider.
&ldquo;&lsquo;Shelob&rsquo; is my name.&rdquo;</p>

However, its heuristics can be overridden by using curly braces to mark a quote as an opener {" or a closer "}:

'}Tis Socrates' season to be jolly!
<p>&rsquo;Tis Socrates&rsquo; season to be jolly!</p>

If you want a straight quote, use a backslash-escape:

5\'11\"
<p>5'11"</p>

A sequence of three periods is parsed as ellipses.

A sequence of three hyphens is parsed as an em-dash.

A sequence of two hyphens is parsed as an en-dash.

57--33 oxen---and no sheep...
<p>57&ndash;33 oxen&mdash;and no sheep&hellip;</p>

Longer sequences of hyphens are divided into em-dashes, en-dashes, and hyphens; uniformly, if possible, and preferring em-dashes, when uniformity can be achieved either way. (So, 4 hyphens become two en-dashes, while 6 hyphens become two em-dashes).

a----b c------d
<p>a&ndash;&ndash;b c&mdash;&mdash;d</p>

Math

To include LaTeX math, put the math in a verbatim span and prefix it with $ (for inline math) or $$ (for display math):

Einstein derived $`e=mc^2`.
Pythagoras proved
$$` x^n + y^n = z^z `
<p>Einstein derived <span class="math inline">\(e=mc^2\)</span>.
Pythagoras proved
<span class="math display">\[ x^n + y^n = z^z \]</span></p>

Footnote reference

A footnote reference is ^ + the reference label in square brackets.

Here is the reference.[^foo]

[^foo]: And here is the note.
<p>Here is the reference.<a href="#fn1" role="doc-noteref"><sup>1</sup></a></p>
<section role="doc-endnotes">
<hr>
<ol>
<li id="fn1">
<p>And here is the note.<a href="#fnref1" role="doc-backlink">↩︎︎</a></p>
</li>
</ol>
</section>

See Footnote, below, for the syntax of the footnote itself.

Line break

Line breaks in inline content are treated as “soft” breaks; they may be rendered as spaces, or (in contexts where newlines are treated semantically like spaces, such as HTML) as as newlines.

To get a hard line break (of the sort represented by HTML’s <br>), use backslash + newline:

This is a soft
break and this is a hard\
break.
<p>This is a soft
break and this is a hard<br>
break.</p>

Comment

Material between two % characters in an attribute will be ignored and treated as a comment. This allows comments to be added to attributes:

{#ident % later we'll add a class %}

But it also serves as a general way to add comments. Just use an attribute specifier that contains only a comment:

Foo bar {% This is a comment, spanning
multiple lines %} baz.
<p>Foo bar  baz.</p>

Emoji

Emojis may be included by surrounding their aliases with : signs:

My reaction is :+1: :smiley:.
<p>My reaction is 👍 😃.</p>

Raw inline

Raw inline content in any format may be included using a verbatim span followed by {=FORMAT}:

This is `<?php echo 'Hello world!' ?>`{=html}.
<p>This is <?php echo 'Hello world!' ?>.</p>

This content is intended to be passed through verbatim when rendering the designated format, but ignored otherwise.

Span

Text in square brackets that is not a link or image and is followed immediately by an attribute is treated as a generic span.

It can be helpful to [read the manual]{.big .red}.
<p>It can be helpful to <span class="big red">read the manual</span>.</p>

Inline attributes

Attributes are put inside curly braces and must immediately follow the inline element to which they are attached (with no intervening whitespace).

Inside the curly braces, the following syntax is possible:

  • .foo specifies foo as a class. Multiple classes may be given in this way; they will be combined.
  • #foo specifies foo as an identifier. An element may have only one identifier; if multiple identifiers are given, the last one is used.
  • key="value" or key=value specifies a key-value attribute. Quotes are not needed when the value consists entirely of ASCII alphanumeric characters or _ or : or -. Backslash escapes may be used inside quoted values.
  • % begins a comment, which ends with the next % or the end of the attribute (}).

Attribute specifiers may contain line breaks.

Example:

An attribute on _emphasized text_{#foo
.bar .baz key="my value"}
<p>An attribute on <em id="foo" class="bar baz" key="my value">emphasized text</em></p>

Attribute specifiers may be “stacked,” in which case they will be combined. Thus,

avant{lang=fr}{.blue}
<p><span lang="fr" class="blue">avant</span></p>

is the same as

avant{lang=fr .blue}
<p><span lang="fr" class="blue">avant</span></p>

Block syntax

As in commonmark, block structure can be discerned prior to inline parsing and takes priority over inline structure.

Indeed, blocks can be parsed line by line with no backtracking. The contribution a line makes to block-level structure never depends on a future line.

Indentation is only significant for list item or footnote nesting.

Block-level items should be separated from one another by blank lines. There are some cases in which two block-level elements can be adjacent—e.g., a thematic break or fenced code block can be directly followed by a paragraph. Indeed, the possibility of line-by-line parsing precludes requiring a blank line after a block-level element. But for readability, we recommend always separating block-level elements by blank lines. Paragraphs can never be interrupted by other block-level elements, and must always end with a blank line (or the end of the document or containing element).

Paragraph

A paragraph is a sequence of nonblank lines that does not meet the condition for being one of the other block-level elements. The textual content is parsed as a sequence of inline elements. Newlines are treated as soft breaks and interpreted like spaces in formatted output. A paragraph ends with a blank line or the end of the document.

Heading

A heading starts with a sequence of one or more # characters, followed by whitespace. The number of # characters defines the heading level. The following text is parsed as inline content.

## A level _two_ heading!
<h2 id="A-level-two-heading">A level <em>two</em> heading!</h2>

The heading text may spill over onto following lines. The heading ends when a blank line (or the end of the document or enclosing container) is encountered.

# A heading that
takes up
three lines

A paragraph, finally.
<h1 id="A-heading-that-takes-up-three-lines">A heading that
takes up
three lines</h1>
<p>A paragraph, finally.</p>

Any number of trailing # characters may be included as a cosmetic decoration; they will not be included in the heading’s content:

### Heading ###
<h3 id="Heading">Heading</h3>

Block quote

A block quote is a sequence of lines, each of which begins with >, followed either by a space or by the end of the line. The contents of the block quote (minus initial >) are parsed as block-level content.

> This is a block quote.
>
> 1. with a
> 2. list in it.
<blockquote>
<p>This is a block quote.</p>
<ol>
<li>
with a
</li>
<li>
list in it.
</li>
</ol>
</blockquote>

As in Markdown, it is possible to “lazily” omit the > prefixes from regular paragraph lines inside the block quote, except in front of the first line of a paragraph:

> This is a block
quote.
<blockquote>
<p>This is a block
quote.</p>
</blockquote>

List item

A list item consists of a list marker followed by a space (or a newline) followed by one or more lines, indented relative to the list marker. For example:

1.  This is a
 list item.

 > containing a block quote
<ol>
<li>
<p>This is a
list item.</p>
<blockquote>
<p>containing a block quote</p>
</blockquote>
</li>
</ol>

Indentation may be “lazily” omitted on paragraph lines following the first line of a paragraph:

1.  This is a
list item.

  Second paragraph under the
list item.
<ol>
<li>
<p>This is a
list item.</p>
<p>Second paragraph under the
list item.</p>
</li>
</ol>

The following basic types of list markers are available:

Marker List type
- bullet
+ bullet
* bullet
1. ordered, decimal-enumerated, followed by period
1) ordered, decimal-enumerated, followed by parenthesis
(1) ordered, decimal-enumerated, enclosed in parentheses
a. ordered, lower-alpha-enumerated, followed by period
a) ordered, lower-alpha-enumerated, followed by parenthesis
(a) ordered, lower-alpha-enumerated, enclosed in parentheses
A. ordered, upper-alpha-enumerated, followed by period
A) ordered, upper-alpha-enumerated, followed by parenthesis
(A) ordered, upper-alpha-enumerated, enclosed in parentheses
i. ordered, lower-roman-enumerated, followed by period
i) ordered, lower-roman-enumerated, followed by parenthesis
(i) ordered, lower-roman-enumerated, enclosed in parentheses
I. ordered, upper-roman-enumerated, followed by period
I) ordered, upper-roman-enumerated, followed by parenthesis
(I) ordered, upper-roman-enumerated, enclosed in parentheses
: definition
- [ ] task

Ordered list markers can use any number in the series: thus, (xix) and v) are both valid lower-roman-enumerated markers, and v) is also a valid lower-alpha-enumerated marker.

Task list item

A bullet list item that begins with [ ], [X], or [x] followed by a space is a task list item, either unchecked ([ ]) or checked ([X] or [x]).

Definition list item

In a definition list item, the first line or lines after the : marker is parsed as inline content and taken to be the term defined. Any further blocks included in the item are assumed to be the definition.

: orange

  A citrus fruit.
<dl>
<dt>orange</dt>
<dd>
<p>A citrus fruit.</p>
</dd>
</dl>

List

A list is simply a sequence of list items of the same type (where each line in the table above defines a type). Note that changing ordered list style or bullet will stop one list and start a new one. Hence the following list items get grouped into four distinct lists:

i) one
i. one (style change)
+ bullet
* bullet (style change)
<ol start="9" type="a">
<li>
one
</li>
</ol>
<ol start="9" type="a">
<li>
one (style change)
</li>
</ol>
<ul>
<li>
bullet
</li>
</ul>
<ul>
<li>
bullet (style change)
</li>
</ul>

Sometimes list items are ambiguous as to type. In this case the ambiguity will be resolved in such a way as to continue the list, if possible. For example, in

i. item
j. next item
<ol start="9" type="a">
<li>
item
</li>
<li>
next item
</li>
</ol>

the first item is ambiguous between lower-roman-enumerated and lower-alpha-enumerated. But only the latter interpretation works for the next item, so we prefer the reading that allows us to have one continuous list rather than two separate ones.

The start number of an ordered list will be determined by the number of its first item. The numbers of subsequent items are irrelevant.

5) five
8) six
<ol start="5">
<li>
five
</li>
<li>
six
</li>
</ol>

A list is classed as tight if it contains blank lines between items, or between blocks inside an item. Blank lines at the start or end of a list do not count against tightness.

- one
- two

  - sub
  - sub
<ul>
<li>
one
</li>
<li>
two
<ul>
<li>
sub
</li>
<li>
sub
</li>
</ul>
</li>
</ul>

A list that is not tight is loose. The intended significance of this distinction is that tight lists should be rendered with less space between items.

- one

- two
<ul>
<li>
<p>one</p>
</li>
<li>
<p>two</p>
</li>
</ul>

Code block

A code block starts with a line of three or more consecutive backticks, optionally followed by whitespace and a language specifier, but nothing else. It ends with a line of backticks equal or greater in length to the opening backtick “fence,” or the end of the document or enclosing block, if no such line is encountered. Its contents are interpreted as verbatim text. If the contents contain a line of backticks, be sure to select a longer string of backticks to use as the “fence”:

````
This is how you do a code block:

``` ruby
x = 5 * 6
```
````
<pre><code>This is how you do a code block:

``` ruby
x = 5 * 6
```
</code></pre>

Here is an example of a code block that is implicitly closed when its parent container is closed;

> ```
> code in a
> block quote

Paragraph.
<blockquote>
<pre><code>code in a
block quote
</code></pre>
</blockquote>
<p>Paragraph.</p>

Thematic break

A line containing four or more * or - characters, and nothing else (except spaces or tabs) is treated is a thematic break (<hr> in HTML). Unlike in Markdown, a thematic break may be indented:

Then they went to sleep.

      * * * *

When they woke up, ...
<p>Then they went to sleep.</p>
<hr>
<p>When they woke up, &hellip;</p>

Raw block

A code block with =FORMAT where the language specification would normally go is interpreted as raw content in FORMAT and will be passed through verbatim to output in that format. For example:

``` =html
<video width="320" height="240" controls>
  <source src="movie.mp4" type="video/mp4">
  <source src="movie.ogg" type="video/ogg">
  Your browser does not support the video tag.
</video>
```
<video width="320" height="240" controls>
  <source src="movie.mp4" type="video/mp4">
  <source src="movie.ogg" type="video/ogg">
  Your browser does not support the video tag.
</video>

Div

A div begins with a line of three or more consecutive colons, optionally followed by white space and a class name (but nothing else). It ends with a line of consecutive colons at least as long as the opening fence, or with the end of the document or containing block.

The contents of a div are interpreted as block-level content.

::: warning
Here is a paragraph.

And here is another.
:::
<div class="warning">
<p>Here is a paragraph.</p>
<p>And here is another.</p>
</div>

Pipe table

A pipe table consists of a sequence of rows. Each row starts and ends with a pipe character (|) and contains one or more cells separated by pipe characters.

A separator line is a row in which every cell consists of a sequence of one of more - characters, optional prefixed and/or suffixed by a : character.

When a separator line is encountered, the previous row is treated as a header, and alignments on that row and any subsequent rows are determined by the separator line (until a new header is found). The separator line itself does not contribute a row to the parsed table.

Column alignments are determined by the separator line in the following way:

  • if the line of - begins with a : and does not end with one, the column is left-aligned
  • if it ends with : and does not begin with one, the column is right-aligned
  • if it both begins and ends with :, the column is center-aligned
  • if it neither begins nor ends with :, the column is default-aligned

Here is an example:

| a  |  b |
|----|:--:|
| 1  | 2  |
|:---|---:|
| 3  | 4  |
<table>
<tr>
<th>a</th>
<th style="text-align: center;">b</th>
</tr>
<tr>
<th style="text-align: left;">1</th>
<th style="text-align: right;">2</th>
</tr>
<tr>
<td style="text-align: left;">3</td>
<td style="text-align: right;">4</td>
</tr>
</table>

Here the row with a and b is a header, with the left column default-aligned and the right column center-aligned. The next real row, containing 1 and 2, is also a header, in which the left column is left-aligned and the right column is right-aligned. This alignment is also applied to the row that follows, containing 3 and 4.

A table need not have a header: just omit any separator lines, or (if you need to specify column alignments) begin with a separator line:

|:--|---:|
| x | 2  |
<table>
<tr>
<td style="text-align: left;">x</td>
<td style="text-align: right;">2</td>
</tr>
</table>

Contents of table cells are parsed as inlines. Block-level content is not possible in pipe table cells.

Djot is smart enough to recognize backslash-escaped pipes and pipes in verbatim spans; these do not count as cell separators:

| just two \| `|` | cells in this table |
<table>
<tr>
<td>just two \</td>
<td><code>|</code></td>
<td>cells in this table</td>
</tr>
</table>

Footnote

A footnote consists of a footnote reference followed by a colon followed by the contents of the note, indented to any column beyond the column in which the reference starts. The contents of the note are parsed as block-level content.

Here's the reference.[^foo]

[^foo]: This is a note
  with two paragraphs.

  Second paragraph.

  > a block quote in the note.
<p>Here&rsquo;s the reference.<a href="#fn1" role="doc-noteref"><sup>1</sup></a></p>
<section role="doc-endnotes">
<hr>
<ol>
<li id="fn1">
<p>This is a note
with two paragraphs.</p>
<p>Second paragraph.</p>
<blockquote>
<p>a block quote in the note.</p>
</blockquote>
<p><a href="#fnref1" role="doc-backlink">↩︎︎</a></p>
</li>
</ol>
</section>

As with block quotes and list items, subsequent lines in paragraphs can “lazily” omit the indentation:

Here's the reference.[^foo]

[^foo]: This is a note
with two paragraphs.

  Second paragraph must
be indented, at least in the first line.
<p>Here&rsquo;s the reference.<a href="#fn1" role="doc-noteref"><sup>1</sup></a></p>
<section role="doc-endnotes">
<hr>
<ol>
<li id="fn1">
<p>This is a note
with two paragraphs.</p>
<p>Second paragraph must
be indented, at least in the first line.<a href="#fnref1" role="doc-backlink">↩︎︎</a></p>
</li>
</ol>
</section>

Block attributes

To attach attributes to a block-level element, put the attributes on the line immediately before the block. Block attributes have the same syntax as inline attributes, but they must fit on one line. Repeated attribute specifiers can be used, and the attributes will accumulate.

{#water}
{.important .large}
Don't forget to turn off the water!

{source="Iliad"}
> Sing, muse, of the wrath of Achilles
<p id="water" class="important large">Don&rsquo;t forget to turn off the water!</p>
<blockquote source="Iliad">
<p>Sing, muse, of the wrath of Achilles</p>
</blockquote>