Djot Syntax Reference

This document covers all Djot syntax supported by this library with input and output examples.

Block Elements

Headings

Headings use # characters. The number of # determines the level (1-6).

Input:

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

<h1>Heading 1</h1>
<h2>Heading 2</h2>
<h3>Heading 3</h3>
<h4>Heading 4</h4>
<h5>Heading 5</h5>
<h6>Heading 6</h6>

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

Paragraphs

Paragraphs are separated by blank lines. Text within a paragraph wraps normally.

Input:

First paragraph with
multiple lines.

Second paragraph.

<p>First paragraph with
multiple lines.</p>
<p>Second paragraph.</p>

First paragraph with multiple lines.

Second paragraph.

Code Blocks

Fenced code blocks use triple backticks with an optional language identifier.

Input:

```php
function hello(): void {
    echo "Hello World";
}
```

<pre><code class="language-php">function hello(): void {
    echo "Hello World";
}
</code></pre>

function hello(): void {
    echo "Hello World";
}

Without a language:

Input:

```
Plain code block
```

<pre><code>Plain code block
</code></pre>

Plain code block

Closing fence is optional

The closing fence may be omitted. An unterminated code block is implicitly closed at the end of its enclosing block (a list item, a block quote) or the end of the document - the same rule the official djot reference uses:

> ```
> code in a block quote

renders the fenced block closed at the end of the quote. A bare ``` with nothing after it is therefore a valid (empty) code block, not an inline code span.

Language specifier must be a single token

After the opening fence, only a single-token language specifier (optionally surrounded by whitespace) is allowed - "nothing else". A would-be info string with internal whitespace is not a code block opener: the backtick form falls through to an inline verbatim span, and the tilde form to a plain paragraph.

Input	Result
```	empty code block
``` php	code block, language-php
``` not a code block	inline <code> span (not a code block)

The enhanced code group syntax (lang [Label]) is the one exception, and only applies to fences that have content lines.

Block Quotes

Block quotes use > at the start of each line.

Input:

> This is a quote
> spanning multiple lines.
>
> With multiple paragraphs.

<blockquote>
<p>This is a quote
spanning multiple lines.</p>
<p>With multiple paragraphs.</p>
</blockquote>

This is a quote spanning multiple lines.

With multiple paragraphs.

Nested block quotes:

Input:

> Outer quote
>
> > Nested quote

<blockquote>
<p>Outer quote</p>
<blockquote>
<p>Nested quote</p>
</blockquote>
</blockquote>

Outer quote

Nested quote

Block Quote Captions

Use ^ after a block quote to add an attribution/caption. The block quote will be wrapped in a <figure> element with a <figcaption>.

Input:

> To be or not to be, that is the question.
^ William Shakespeare

<figure>
<blockquote>
<p>To be or not to be, that is the question.</p>
</blockquote>
<figcaption>William Shakespeare</figcaption>
</figure>

To be or not to be, that is the question.

William Shakespeare

Lists

Bullet Lists

Use -, *, or + for bullet lists.

Input:

- Item 1
- Item 2
- Item 3

<ul>
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3</li>
</ul>

• Item 1
• Item 2
• Item 3

Ordered Lists

Use numbers followed by . or ).

Input:

1. First
2. Second
3. Third

<ol>
<li>First</li>
<li>Second</li>
<li>Third</li>
</ol>

1. First
2. Second
3. Third

Lists can start at any number:

Input:

5. Fifth item
6. Sixth item

<ol start="5">
<li>Fifth item</li>
<li>Sixth item</li>
</ol>

5. Fifth item
6. Sixth item

Empty List Items

A list marker may be followed by a space or by the end of the line, so a bare marker on its own line is a valid empty item. This works for every marker type (-, *, +, 1., (1), a., i.).

Input:

- One
-
- Three

<ul>
<li>One</li>
<li></li>
<li>Three</li>
</ul>

• One
• Three

Nested Lists

Indent with 2+ spaces for nested lists.

Input:

- Item 1
  - Nested A
  - Nested B
- Item 2

<ul>
<li>Item 1
<ul>
<li>Nested A</li>
<li>Nested B</li>
</ul>
</li>
<li>Item 2</li>
</ul>

• Item 1
  • Nested A
  • Nested B
• Item 2

Task Lists

Use [ ] or [_] for unchecked and [x] or [X] for checked items.

The underscore notation [_] is useful on mobile devices or in editors without monospaced fonts, where the space in [ ] can be hard to type or see.

Input:

- [ ] Todo item (space)
- [_] Todo item (underscore)
- [x] Done item

<ul class="task-list">
<li><input type="checkbox" disabled> Todo item (space)</li>
<li><input type="checkbox" disabled> Todo item (underscore)</li>
<li><input type="checkbox" disabled checked> Done item</li>
</ul>

• Todo item (space)
• Todo item (underscore)
• Done item

List Item Attributes (Extension)

Attributes can be attached to a list item by placing them in curly braces immediately after the marker, with no space before the brace (per the djot proposal jgm/djot#262):

Input:

+{.blue} A blue list item.
+{#id1 .highlight} Item with id and class.
1.{data-value="test"} Numbered item with a data attribute.

<ul>
<li class="blue">A blue list item.</li>
<li id="id1" class="highlight">Item with id and class.</li>
</ul>
<ol>
<li data-value="test">Numbered item with a data attribute.</li>
</ol>

• A blue list item.
• Item with id and class.

1. Numbered item with a data attribute.

Works with every marker type (bullet, ordered, parenthesized, roman, alpha, and task lists). A space between the marker and the brace changes the meaning: + {.blue} makes the {.blue} ordinary item content (a block attribute for the following block inside the item), not an attribute on the <li>.

Soft-deprecated alternative

Attributes can also be added on the following indented line. This older form still attaches to the <li>, but the marker-adjacent form above is now the preferred syntax.

Input:

- item 1
  {.highlight #id1}
- item 2
  {data-value="test"}
- item 3

<ul>
<li class="highlight" id="id1">item 1</li>
<li data-value="test">item 2</li>
<li>item 3</li>
</ul>

• item 1
• item 2
• item 3

Works with all list types (unordered, ordered, and task lists). The attribute line must be indented to the content indentation level.

The {...} line attaches to the <li> only when it is the last content line of the item. If another block follows it within the same item, the {...} behaves as a standard djot block attribute for that following block, and the list / item are not terminated:

- item
  {.note}
  > a quoted aside inside the item

renders as:

<ul>
<li>
item
<blockquote class="note">
<p>a quoted aside inside the item</p>
</blockquote>
</li>
</ul>

Tight vs Loose Lists

Lists in Djot can be tight or loose, which affects how list items are rendered.

Tight lists have no blank lines between items. List item content is rendered directly without <p> tags:

Input:

- Item one
- Item two
- Item three

<ul>
<li>Item one</li>
<li>Item two</li>
<li>Item three</li>
</ul>

• Item one
• Item two
• Item three

Loose lists have blank lines between items. Each item's content is wrapped in <p> tags:

Input:

- Item one

- Item two

- Item three

<ul>
<li><p>Item one</p></li>
<li><p>Item two</p></li>
<li><p>Item three</p></li>
</ul>

• Item one

• Item two

• Item three

The tight/loose distinction affects visual spacing. Loose lists typically have more vertical space between items due to paragraph margins in CSS.

Mixed Lists

A list is loose if any item is separated by a blank line. One blank line makes the entire list loose.

Nested lists require a blank line before the nested content in standard Djot:

- Parent item

  - Nested item A
  - Nested item B

With nestedListsWithoutBlankLine mode enabled, nested lists can appear immediately without a blank line:

- Parent item
  - Nested item A
  - Nested item B

See the Parser Options guide for more on nestedListsWithoutBlankLine mode.

Definition Lists

Terms are prefixed with : and definitions are indented below.

Basic

: Term 1

  Definition of term 1

: Term 2

  Definition of term 2

Multiple Terms

: color
: colour

  The visual property of objects.

Multiple Definitions

: word

  First meaning.

: +

  Second meaning (separate dd).

<dl>
<dt>Term 1</dt>
<dd><p>Definition of term 1</p></dd>
<dt>Term 2</dt>
<dd><p>Definition of term 2</p></dd>
</dl>

Term 1

Definition of term 1

Term 2

Definition of term 2

Enhancements

• Multiple terms: Consecutive : term lines share a definition
• Multiple definitions: Use : + continuation for separate <dd> elements
• Attributes: Add {.class} to <dl>, <dt>, or <dd> elements

See definition list enhancements for full details.

Definition List Attributes (Extension)

Attributes can be attached to individual definition list elements:

Input:

{.vocabulary}
: color
{.american}
: colour
{.british}

  The visual property of objects.
  {.primary}

<dl class="vocabulary">
<dt class="american">color</dt>
<dt class="british">colour</dt>
<dd class="primary">
<p>The visual property of objects.</p>
</dd>
</dl>

color

colour

The visual property of objects.

• {...} before first term → applies to <dl>
• {...} on line after term → applies to that <dt>
• {...} as last line in definition block → applies to that <dd>

Tables

Tables use | to separate columns.

Input:

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |

<table>
<thead>
<tr><th>Header 1</th><th>Header 2</th></tr>
</thead>
<tbody>
<tr><td>Cell 1</td><td>Cell 2</td></tr>
<tr><td>Cell 3</td><td>Cell 4</td></tr>
</tbody>
</table>

Header 1	Header 2
Cell 1	Cell 2
Cell 3	Cell 4

Column Alignment

Use : in the separator row for alignment.

Input:

| Left | Center | Right |
|:-----|:------:|------:|
| L    | C      | R     |

<table>
<thead>
<tr><th style="text-align: left">Left</th><th style="text-align: center">Center</th><th style="text-align: right">Right</th></tr>
</thead>
<tbody>
<tr><td style="text-align: left">L</td><td style="text-align: center">C</td><td style="text-align: right">R</td></tr>
</tbody>
</table>

Left	Center	Right
L	C	R

Table Captions

Use ^ after the table for a caption.

Input:

| A | B |
|---|---|
| 1 | 2 |
^ This is the caption

<table>
<caption>This is the caption</caption>
<thead>
<tr><th>A</th><th>B</th></tr>
</thead>
<tbody>
<tr><td>1</td><td>2</td></tr>
</tbody>
</table>

This is the caption

A	B
1	2

Table Row and Cell Attributes (Extension)

Attributes can be added to table rows and individual cells:

Row attributes (after final pipe):

| Name | Age |{.header-row}
|------|-----|
| John | 30  |{.highlight}

Cell attributes (after opening pipe):

|{.name} Name |{.age} Age |
|-------------|-----------|
|{.emphasis} John | 30 |

<table>
<tr class="header-row">
<th class="name">Name</th>
<th class="age">Age</th>
</tr>
<tr class="highlight">
<td class="emphasis">John</td>
<td>30</td>
</tr>
</table>

Name	Age
John	30

Table Multi-line Cells, Rowspan, and Colspan (Extension)

Multi-line cell content uses + prefix for continuation rows:

| Name | Description      |
|------|------------------|
| Item | Long description |
+      | continued here   |

Rowspan uses ^ marker (points UP to cell above):

| Category | Item   |
|----------|--------|
| Fruits   | Apple  |
| ^        | Banana |
| ^        | Orange |

<table>
<tr><th>Category</th><th>Item</th></tr>
<tr><td rowspan="3">Fruits</td><td>Apple</td></tr>
<tr><td>Banana</td></tr>
<tr><td>Orange</td></tr>
</table>

Category	Item
Fruits	Apple
	Banana
	Orange

Colspan uses < marker (points LEFT to cell before):

| Name  | Contact Info | <     |
|-------|--------------|-------|
| Alice | alice@ex.com | x5234 |

<table>
<tr><th>Name</th><th colspan="2">Contact Info</th></tr>
<tr><td>Alice</td><td>alice@ex.com</td><td>x5234</td></tr>
</table>

Name	Contact Info
Alice	alice@ex.com	x5234

Use \^ or \< for literal characters. Content like a < b is NOT treated as colspan.

Thematic Breaks

Use ***, ---, or ___ (3+ characters) on a line by itself.

Input:

Above

***

Below

<p>Above</p>
<hr>
<p>Below</p>

Above

---

Below

Divs

Fenced divs use ::: with an optional class name.

Input:

::: warning
This is a warning message.
:::

<div class="warning">
<p>This is a warning message.</p>
</div>

This is a warning message.

Nested divs:

Input:

::: outer
Outer content

::: inner
Inner content
:::

More outer
:::

<div class="outer">
<p>Outer content</p>
<div class="inner">
<p>Inner content</p>
</div>
<p>More outer</p>
</div>

Outer content

Inner content

More outer

Closing fence is optional

Like code blocks, the closing ::: may be omitted - an unterminated div is implicitly closed at the end of its enclosing block or the document.

Comments

Comments are not rendered in output.

Input:

Visible text

{% This is a comment %}

More visible text

{% Multi-line
   comment here %}

<p>Visible text</p>
<p>More visible text</p>

Visible text

More visible text

Fenced Comments (Extension)

Standard {% %} comments cannot contain blank lines. For longer comments that need blank lines, use fenced comments with %%%:

Input:

Visible text

%%%
This is a fenced comment block.

It can contain blank lines.

Multiple paragraphs of notes, TODOs,
or documentation that won't render.
%%%

More visible text

<p>Visible text</p>
<p>More visible text</p>

Visible text

More visible text

Like code fences, you can use more than three % characters. The closing fence must have at least as many % as the opening fence:

Input:

Some text

%%%%
%%% This is not the end
Still inside the comment
%%%%

More text

<p>Some text</p>
<p>More text</p>

Some text

More text

Note: This is a djot-php extension, not part of the official Djot specification. See discussion for background.

Fenced comment blocks are block-level elements that break paragraph continuity. Unlike other block elements, fenced comments can interrupt paragraphs without requiring a preceding blank line - making them truly "invisible" from a formatting perspective:

Input:

Lorem ipsum
%%%
comment
%%%
dolor sit amet

<p>Lorem ipsum</p>
<p>dolor sit amet</p>

Lorem ipsum

dolor sit amet

This produces two separate paragraphs. For comments that should not interrupt paragraph flow (keeping text in the same paragraph), use inline comments ({% ... %}).

Line Blocks

Preserve line breaks using | at the start of each line. Useful for poetry or addresses. This is a djot-php addition beyond the core spec; see Enhancements.

Input:

| Roses are red,
| Violets are blue,
| Sugar is sweet,
| And so are you.

<div class="line-block">
<p>Roses are red,<br>
Violets are blue,<br>
Sugar is sweet,<br>
And so are you.</p>
</div>

Roses are red,
Violets are blue,
Sugar is sweet,
And so are you.

Fenced alternative

Prefer not to prefix every line? The LineBlockDivExtension adds a fenced form, ::: |, that produces the same line-block div without the per-line |. Leading indentation and medial alignment gaps are preserved, and a blank line separates stanzas.

Block Attributes

For an overview of where attributes attach for each block construct (lists, definition lists, tables, etc.), see Attachment Model in the reference.

Apply attributes to the following block using {...} syntax.

Input:

{.highlight #intro}
# Introduction

{.note data-version="2.0"}
This is a note.

<h1 class="highlight" id="intro">Introduction</h1>
<p class="note" data-version="2.0">This is a note.</p>

Introduction

This is a note.

Boolean Attribute Shorthand (Extension)

Boolean/flag attributes can be specified without a value:

Input:

{reversed}
1. Third
2. Second
3. First

[Download](file.zip){download .btn}

<ol reversed="">
<li>Third</li>
<li>Second</li>
<li>First</li>
</ol>
<p><a href="file.zip" class="btn" download="">Download</a></p>

1. Third
2. Second
3. First

Download

Common boolean attributes: {reversed} (lists), {open} (details), {hidden}, {download} (links).

Inline Elements

Emphasis and Strong

Use _underscores_ for emphasis and *asterisks* for strong.

Input:

This is _emphasized_ and *strong* text.

You can _nest *strong* inside_ emphasis.

<p>This is <em>emphasized</em> and <strong>strong</strong> text.</p>
<p>You can <em>nest <strong>strong</strong> inside</em> emphasis.</p>

This is emphasized and strong text.

You can nest strong inside emphasis.

Code Spans

Use backticks for inline code.

Input:

Use the `print()` function.

For literal backticks: `` `code` ``

<p>Use the <code>print()</code> function.</p>
<p>For literal backticks: <code>`code`</code></p>

Use the print() function.

For literal backticks: `code`

Links

Inline Links

Input:

[Link text](https://example.com)

[Link with title](https://example.com "Title")

<p><a href="https://example.com">Link text</a></p>
<p><a href="https://example.com" title="Title">Link with title</a></p>

Link text

Link with title

Reference Links

Input:

[Link text][ref]

[Another link][ref]

[ref]: https://example.com

<p><a href="https://example.com">Link text</a></p>
<p><a href="https://example.com">Another link</a></p>

Link text

Another link

Reference Links with Attributes

Attributes can be added to reference definitions and will be applied to all links using that reference.

Input:

[Click here][example]

{.external title="Example Site"}
[example]: https://example.com

<p><a href="https://example.com" class="external" title="Example Site">Click here</a></p>

Click here

Link-level attributes can override or extend definition attributes:

Input:

[Click here][example]{.button}

{.external}
[example]: https://example.com

<p><a href="https://example.com" class="external button">Click here</a></p>

Click here

Autolinks

Input:

<https://example.com>

<user@example.com>

<p><a href="https://example.com">https://example.com</a></p>
<p><a href="mailto:user@example.com">user@example.com</a></p>

https://example.com

user@example.com

Images

Input:

![Demo landscape](/demo.svg)

![Demo landscape](/demo.svg "A simple landscape")

<p><img src="/demo.svg" alt="Demo landscape"></p>
<p><img src="/demo.svg" alt="Demo landscape" title="A simple landscape"></p>

Image Captions

Use ^ after an image to add a caption. The image will be wrapped in a <figure> element with a <figcaption>.

Input:

![Demo landscape](/demo.svg)
^ A simple landscape with sun, hills, and sky

<figure>
<img src="/demo.svg" alt="Demo landscape"><figcaption>A simple landscape with sun, hills, and sky</figcaption>
</figure>

A simple landscape with sun, hills, and sky

Superscript and Subscript

Use ^ for superscript and ~ for subscript.

Input:

E=mc^2^

H~2~O

<p>E=mc<sup>2</sup></p>
<p>H<sub>2</sub>O</p>

E=mc²

H₂O

Highlight, Insert, Delete

Input:

{=highlighted text=}

{+inserted text+}

{-deleted text-}

<p><mark>highlighted text</mark></p>
<p><ins>inserted text</ins></p>
<p><del>deleted text</del></p>

highlighted text

inserted text

deleted text

Spans with Attributes

Apply attributes to inline text.

Input:

[styled text]{.highlight}

[more text]{#unique-id}

[data text]{data-value="42"}

<p><span class="highlight">styled text</span></p>
<p><span id="unique-id">more text</span></p>
<p><span data-value="42">data text</span></p>

styled text

more text

data text

Math

Inline Math

Input:

The equation $`E = mc^2`$ is famous.

<p>The equation <span class="math inline">\(E = mc^2\)</span> is famous.</p>

The equation \(E = mc^2\) is famous.

Display Math

Input:

$$`\sum_{i=0}^{n} i = \frac{n(n+1)}{2}`$$

<span class="math display">\[\sum_{i=0}^{n} i = \frac{n(n+1)}{2}\]</span>

\[\sum_{i=0}^{n} i = \frac{n(n+1)}{2}\]

Symbols

Use :name: for symbols.

Input:

I :heart: Djot

<p>I <span class="symbol">heart</span> Djot</p>

I heart Djot

Note: Symbol rendering can be customized via events. See the Cookbook for examples.

Footnotes

Input:

Here is a statement[^1] with a footnote.

Another reference[^note].

[^1]: This is the first footnote.

[^note]: This is a named footnote.

<p>Here is a statement<sup id="fnref-1-1"><a href="#fn-1">1</a></sup> with a footnote.</p>
<p>Another reference<sup id="fnref-note-1"><a href="#fn-note">note</a></sup>.</p>
<div class="footnote" id="fn-1">
<p><sup>1</sup> This is the first footnote. <a href="#fnref-1-1">↩</a></p>
</div>
<div class="footnote" id="fn-note">
<p><sup>note</sup> This is a named footnote. <a href="#fnref-note-1">↩</a></p>
</div>

Here is a statement¹ with a footnote.

Another reference^note.

¹ This is the first footnote. ↩

^note This is a named footnote. ↩

Raw HTML

Inline Raw HTML

Input:

Text `<span class="special">raw html</span>`{=html} more text

<p>Text <span class="special">raw html</span> more text</p>

Text raw html more text

Block Raw HTML

Input:

``` =html
<div class="custom">
  <p>Raw HTML block</p>
</div>
```

<div class="custom">
  <p>Raw HTML block</p>
</div>

Raw HTML block

Smart Typography

The parser automatically converts certain character sequences.

Quotes

Input:

"Double quotes" and 'single quotes'

"Nested 'quotes' work" too

<p>"Double quotes" and 'single quotes'</p>
<p>"Nested 'quotes' work" too</p>

"Double quotes" and 'single quotes'

"Nested 'quotes' work" too

Dashes

Input:

En-dash: 1--10

Em-dash: wait---what?

<p>En-dash: 1–10</p>
<p>Em-dash: wait—what?</p>

En-dash: 1–10

Em-dash: wait—what?

Ellipsis

Input:

Wait for it...

<p>Wait for it…</p>

Wait for it…

Hard Line Breaks

End a line with a backslash for a hard break.

Input:

Line one\
Line two\
Line three

<p>Line one<br>
Line two<br>
Line three</p>

Line one
Line two
Line three

Abbreviations (Extension)

Abbreviations allow you to define terms that will automatically be wrapped in <abbr> tags with their definitions. This is an extension feature inspired by PHP Markdown Extra.

Input:

The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

<p>The <abbr title="Hyper Text Markup Language">HTML</abbr> specification is maintained by the <abbr title="World Wide Web Consortium">W3C</abbr>.</p>

The HTML specification is maintained by the W3C.

Abbreviation definitions can appear anywhere in the document and will be applied to all matching text. Matching is:

• Case-sensitive (HTML ≠ html)
• Word-boundary aware (HTML won't match HTMLElement)

Definitions can span multiple lines if continuation lines are indented:

*[HTML]: Hyper Text Markup Language,
  the standard markup language for documents
  designed to be displayed in a web browser

Inline Abbreviations

For one-off abbreviations or to override a definition, use the inline span syntax:

Input:

The [HTML]{abbr="Hyper Text Markup Language"} specification.

<p>The <abbr title="Hyper Text Markup Language">HTML</abbr> specification.</p>

The HTML specification.

The definition-based approach (*[ABBR]: ...) automatically applies to all matching text, while the inline [ABBR]{abbr="..."} approach allows marking specific occurrences.

Escaping

Use backslash to escape special characters.

Input:

\*not strong\*

\# not a heading

\[not a link\]

<p>*not strong*</p>
<p># not a heading</p>
<p>[not a link]</p>

*not strong*

# not a heading

[not a link]

Non-Breaking Space

An escaped space (\ ) produces a non-breaking space.

Input:

100\ km

Dr.\ Smith

<p>100&nbsp;km</p>
<p>Dr.&nbsp;Smith</p>

100 km

Dr. Smith

This is useful for keeping values and units together, titles and names, or any text that shouldn't be split across lines.