LibreTimes Markdown and CommonMark

LibreTimes Markdown is CommonMark with GitHub's extensions, plus a small set of additions for mathematical and scholarly writing. If you have written Markdown on GitHub, in a notebook or in a static-site generator, almost everything you know carries over. This page says what carries over unchanged, what is added, the few places where the dialect behaves differently, and what it deliberately does not do.

The same as CommonMark and GitHub

Paragraphs, headings, emphasis, lists, links, images, block quotes, code spans and fenced code blocks follow CommonMark exactly. From GitHub Flavored Markdown the dialect takes tables, task lists, footnotes, autolinks and ~~strikethrough~~.

A plain CommonMark document is therefore already a valid LibreTimes document, and it renders the way you expect. The basics pages cover this layer, mostly so that they can point out the edge cases.

What is added

Each addition answers a need that plain Markdown leaves to raw HTML or to an image of the result.

• Mathematics, written as LaTeX between dollar signs, $x^2$ in a line and $$ on lines of their own for a display. It is the one place where LaTeX is the syntax, because there is no better notation for formulae and every mathematician already writes it. See Write mathematics.
• Directives, the :::name … ::: blocks. A theorem, a proof, a warning, a figure with a caption, a collapsible solution, a group of tabs and a TikZ diagram are all directives, so one syntax covers every block the dialect adds. The syntax reference lists every name.
• Inline marks: ==highlight==, ~sub~ and ^super^ scripts, and definition lists.
• Block attributes, a line such as {align=center} or {#key-table} directly above a block, for the few properties a block can have: how its lines sit, how its first line is indented, and an anchor others can link to.
• People and files: @handle links a person's profile, and :attach[…] links a file attached to the work.
• Video, @[youtube](…) and @[vimeo](…), the only two embedded players.

What is changed

Four rules differ from what another Markdown would do with the same text. Each has a reason, and each is a place where a document written elsewhere can surprise you.

A single tilde is a subscript

H~2~O is a subscript, and strikethrough needs two tildes on each side, ~~like this~~. GitHub accepts a single tilde for strikethrough as well; here that form would swallow every chemical formula, so it is switched off. GitHub also renders the two-tilde form, so a document written for both reads the same.

Two hyphens are a dash

-- becomes an en dash and --- an em dash, in documents and in titles. Quotes and ellipses are left exactly as typed, because the right quotation marks depend on the language and a wrong guess is worse than straight quotes. To keep hyphens as hyphens, put them in inline code: `--verbose`.

The title is the top heading

The title you give a work is the page's only top-level heading, so the text starts its sections at ## and goes down to ####. A document that does use #, such as one written elsewhere, is not flattened: every heading in it moves down one level, so its sections keep their order and nesting. Levels below the fourth merge into the fourth.

The reason is the outline. A page with two top-level headings gives a screen reader two documents, a search engine two titles, and the table of contents beside the text a tree with two roots. Moving every heading keeps what you wrote and gives the page one title.

Raw HTML is filtered

HTML in the source is allowed and passes through a filter that keeps a short list of harmless elements and removes everything else: scripts, styles, forms and frames other than the video players. See HTML and security.

What the dialect refuses

The rule behind the additions is that markup says what a thing is, never how it looks. A theorem is marked as a theorem, and its bold label and italic body follow from that, on the page, in a PDF and in a screen reader alike. The same rule rules some things out for good, so they are not reconsidered one request at a time:

• Fonts, sizes, colours and spacing. They belong to the page that shows the text, not to the text. A passage that needs to stand out is a highlight, an admonition or a statement, each of which says why it stands out.
• Lengths. A block can be centred or have a hanging indent, named values that every output can honour in its own measure. It cannot be given a width or a margin in centimetres.
• Columns, floats and page breaks. Page layout belongs to an export, not to the source that every output shares.
• LaTeX outside maths. \begin{theorem}, \section and \emph are not read in the text. A .tex file reaches the platform through import, which rewrites them into the dialect once, rather than every reader's page parsing LaTeX forever.
• Line breaks copied from a printed page. Prose reflows to the reader's screen. Verse keeps its lines, in a verse block.

A typo stays visible

The dialect's vocabulary is closed: there is a fixed set of directive names and attribute keys. Anything outside it renders as the characters you typed. A misspelt :::theorm shows its fence lines on the page, with the body between them still rendered as Markdown, and {alig=center} is printed instead of being ignored.

That is deliberate. A renderer that guessed would turn a typo into a silent change of meaning, and a renderer that dropped what it did not know would hide it. The honest output is what you wrote, where a proof-reader will see it.

Shorter fields take less

Titles, abstracts, biographies and CV entries are written in Markdown too, but not the whole dialect, because they are shown in places where a block cannot go: a browser tab, a search result, a citation export.

Anything else in those fields is shown as its plain text. $$ is not maths there: a display formula in a title is never what was meant. Comments take the text formatting and the maths but no media and no blocks; see Comments.

One syntax for stored text

Some constructs have a second spelling elsewhere that LibreTimes reads only on import. GitHub's > [!NOTE] alert is the main one: typed into a document, it stays an ordinary block quote; in a file you import, it becomes a :::note. Keeping one spelling for what is stored means every document can be edited, searched and converted by the same rules, and two writers never disagree about which form is current.