Page and Section Markup

Page and section headers use a compact syntax with a leading equals sign. Sections are handled automatically from the headers. Attribute lists may follow headers.

Notes

Pages may have any number of parser directives at the top, each starting with the @ character. See Parser Directives for details.
After directives, pages begin with a page title on a line that starts with an equals sign that is followed by a space.
Sections start with section titles, each on a line that starts with two or more equals signs that are followed by a space. Specify section depth with the number of equals signs. Sections end implicitly with new sections at the same or higher levels.
A page and section title may be followed by a subtitle on a line that starts with hyphens that are followed by a space. The number of hyphens matches the number of equals signs used for the corresponding title.
Following a title or an optional subtitle, there may be an attribute list indented by at least one space to disambiguate it from block content.
Page and section titles are followed by optional informational elements, each on a line that starts with the @ character. See Informational Elements for details.
All other content is block content. See Block Elements for details.

Examples

Create a simple page:

= My Page Title

This is a paragraph.

<page xmlns="http://projectmallard.org/1.0/">
  <title>My Page Title</title>
  <p>This is a paragraph.</p>
</page>

Create a page with a subtitle:

= My Page Title
- My Page Subtitle

This is a paragraph.

<page xmlns="http://projectmallard.org/1.0/">
  <title>My Page Title</title>
  <subtitle>My Page Subtitle</subtitle>
  <p>This is a paragraph.</p>
</page>

Titles and subtitles can span multiple lines. Indent at least one space to keep subsequent lines in the title or subtitle:

= This Is a Very Long Title that
  Wraps onto the Next Line
- This Is a Very Long Subtitle that
  Wraps onto the Next Line

This is a paragraph.

<page xmlns="http://projectmallard.org/1.0/">
  <title>This Is a Very Long Title that Wraps onto the Next Line</title>
  <subtitle>This Is a Very Long Subtitle that Wraps onto the Next Line</title>
  <p>This is a paragraph.</p>
</page>

Attribute lists for pages and sections follow the title or subtitle and start with at least one space that is followed by a left square bracket:

= My Page Title
  [style=tutorial]

This is a paragraph.

<page xmlns="http://projectmallard.org/1.0/" style="tutorial">
  <title>My Page Title</title>
  <p>This is a paragraph.</p>
</page>

Create a page with sections and subsections:

= My Page Title

== My Section Title
-- My Section Subtitle

This is a paragraph.

=== My Subsection Title

This is another paragraph.

<page xmlns="http://projectmallard.org/1.0/">
  <title>My Page Title</title>

  <section>
    <title>My Section Title</title>
    <subtitle>My Section Subtitle</subtitle>

    <p>This is a paragraph.</p>

    <section>
      <title>My Subsection Title</title>

      <p>This is another paragraph.</p>
    </section>
  </section>
</page>

Specification

A line that starts with an equals sign and at least one space is a page title. A line that starts with two or more equals signs and a space is a section title. Only one page title is allowed, and the page title must occur before any other block-level content. (Directives may come before the page title.)

Each subsequent line is considered part of the page or section title as long as the line is indented by at least one space and does not start with a left square bracket. The full title is the concatenation of all such lines, parsed as inline content.

A section title automatically creates a section at the correct depth. The number of equals signs that start the section title line is two greater than the number of ancestor section elements of the new section. The parser closes as many sections as necessary. It is an error if the new section is more than one level deeper than the current section.

Following a page or section title:

If the line begins with the same number of hyphen characters as the number of equals signs starting the title, followed by a space, then that line starts a page or section subtitle.
If the line starts with at least one space followed by a left square bracket, then that line starts an attribute list for the page or section.
If the line starts with the @ character, possibly preceded by spaces, then that line begins an informational element.
If the line is blank, it may be followed by informational elements but not a subtitle or attribute list.
Otherwise, regular block content begins.

A page or section subtitle immediately follows a title and begins with the same number of hyphen characters as the title has equals signs, plus a single space. Each subsequent line is part of the subtitle as long as the line is indented by at least one space and does not start with a left square bracket. The full subtitle is the concatenation of all such lines, parsed as inline content.

Following a page or section subtitle:

If the line starts with at least one space and a left square bracket, then that line starts an attribute list for the page or section.
If the line starts with the @ character, possibly preceded by spaces, then that line begins an informational element.
If the line is blank, it may be followed by informational elements but not an attribute list.
Otherwise, regular block content begins.

An attribute list for a page or section follows the title or subtitle (but may not be between them) and starts with at least one space followed by a left square bracket. Note that the leading space is necessary to disambiguate from regular block content.