Directives

MDLeaf adds a handful of directives for pagination features. A directive is a single line:

::name
::name[label]
::name{attrs}
::name[label]{attrs}

Directive	What it does	Page
`::pagebreak`	Starts a new page	Page breaks
`::toc`	Table of contents with page numbers	Table of contents
`::header[…]`, `::footer[…]`	Running header or footer from this page on	Headers and footers
`::hide{…}`	Hides header and/or footer on one page	Hiding headers
`::pagenumber{…}`	Restarts or offsets the page numbers	Page numbering

::header[Annual report||2026]
::footer[|Page {page} of {pages}|]

# Annual Report 2026

Prepared for the board.

::pagebreak
::hide{header}

::toc{depth=2}

::pagebreak
::pagenumber{start=1}

## Summary

MDLeaf lays Markdown out on real pages. Paragraphs flow from page to page, and the page view shows exactly what the PDF will contain.

MDLeaf lays Markdown out on real pages. Paragraphs flow from page to page, and the page view shows exactly what the PDF will contain.

::pagebreak

## Results

MDLeaf lays Markdown out on real pages. Paragraphs flow from page to page, and the page view shows exactly what the PDF will contain.

MDLeaf lays Markdown out on real pages. Paragraphs flow from page to page, and the page view shows exactly what the PDF will contain.

A cover page without header and footer, a contents page, and numbering that restarts at 1 for the first chapter. {pages} counts the displayed numbers.

Download sample (.mdl)

Open it in MDLeaf with Library → Import .mdl. If MDLeaf is installed, you can also open the file directly.

Grammar

directive  = "::" name [ "[" label "]" ] [ "{" attrs "}" ] *WSP EOL
name       = lowercase letter, then lowercase letters, digits or "-"
label      = any text; write "\]" for "]" and "\|" for a literal "|"
attrs      = zero or more attributes separated by spaces
attr       = key "=" value / key            ; a bare key is a flag
value      = text without spaces, or "a quoted value" (\" for a quote)

Where directives work

At the start of a line (column 0), with nothing else on the line.
At the top level of the document: not inside a list, quote, table, code block or footnote.
A directive line may follow a paragraph directly; it always ends that paragraph.
To write the characters literally, escape them: \::pagebreak shows ::pagebreak.

The editor highlights directives in violet, their labels in a lighter violet and attributes in teal.

Common mistakes

Problem	Diagnostic
A misspelt name such as `::pagebrake` stays as text	`directive-unknown` (warning)
An indented directive, or one inside a list or quote, stays as text	`directive-misplaced` (warning)
An attribute the directive does not have is ignored	`directive-attr-unknown` (warning)
An invalid value, such as `::toc{depth=9}`, ignores the whole directive	`directive-attr-invalid` (error)

See all diagnostics.