Skip to content

Markdown Conventions ​

Typoteka accepts standard Markdown and adds a small set of conventions for book layout.

Standard Markdown ​

You can use all the usual Markdown: headings, lists, emphasis, links, tables, code, and blockquotes. Markdown Basics explains each of them, and what they mean in a book.

Fenced divs ​

A block fenced with ::: becomes a <div> with the classes you specify. This is how you apply a book style's layout features to a region of content.

Use an attribute block with class names prefixed by .:

markdown
::: {.box}
This content is wrapped in a div with class "box".
:::

As a shorthand, you can write bare words instead of the attribute block. A single bare word becomes one class:

markdown
::: box
A bordered box.
:::

Multiple bare words become multiple classes:

markdown
::: span unjustify
Content with classes "span" and "unjustify".
:::

Style-defined classes ​

The classes only mean something because the active book style styles them. Which classes exist, and how they look, depends on the style you have chosen.

Two common ones:

  • .box: a bordered box.
  • .span: content that spans the full text width across columns.
  • .span-2, .span-2-right, .span-2-bottom, .span-2-right-bottom: a table or image across two of the columns, at the top or the foot of the page (.span-3…: three).

Headings and structure ​

Headings drive the document structure: their levels make the sections, and the table of contents and the running heads read them. Headings are not numbered; the Number sections plugin (Project Settings → Advanced) adds the numbers to the HTML, but the shared layer hides them, in every style.

Short titles for running heads ​

Some styles print the current chapter or section in the page margins. A long title can have a shorter form for them, written in the heading's attributes:

markdown
# Part XI: The Weapons of the Jedi {short="Weapons of the Jedi"}

The heading itself still reads in full; only running heads use the short form, in the styles that print them. Quote the value, in double or single quotes, when it has spaces. It sits with the heading's other attributes: {#weapons .onecolumn short="Weapons"}.

Classes on a chapter heading ​

A class on a chapter's heading (#) applies to the whole chapter: the pipeline moves it from the heading to the section around it, which runs up to the next #. Some styles define classes for it; a style that has them lists them on its page, under Chapter classes. In D&D 5th Edition, for instance, one picks the chapter's section colour:

markdown
# Chapter 9: Combat {.section-blue}

The class applies to every page of the chapter, up to the next chapter heading, and what it changes depends on the style:

  • In D&D 5th Edition there are five colours (section-green, section-ochre, section-blue, section-purple, section-red), in pale tones: the corner of the page's footer, the background of notes and the stripes of tables. A chapter without a class is green.
  • In D&D 5th Edition DMG there are the same five and a sixth, section-grey, in deeper tones: the footer's corner is nearly solid. A chapter without a class is red.

A chapter with a class keeps its colour when the book moves from one of these styles to the other, paler in one and deeper in the other. A chapter without a class takes each style's default (green or red), and section-grey, which D&D 5th Edition does not have, falls back to its green.

Table of contents ​

The book's settings can add a table of contents at the beginning or at the end (Project Settings → Basic → Book structure, or contents in typoteka.json). To put it somewhere else, write an empty block with the id contents where it should go:

markdown
::: {#contents}
:::

The table lists every chapter (a # heading when the book's chapter headings setting is on, or the first heading of each ::: chapter block) and two levels of sections inside it. A heading with the class no-toc stays out of it:

markdown
## Notes for the printer {.no-toc}