Docs

Troubleshooting Markdown

Fix a red formula, a directive or attribute line shown as text, an image that does not open, an unrendered diagram, or a citation left as typed.

On this page

Each section below starts from what you see on the page. Check the preview in the editor first: it renders exactly what readers will see, so a problem that shows there is in the source, not in the site.

A formula renders in red

A formula that KaTeX cannot render is shown in place, in red, with your source, rather than breaking the page. The usual causes:

  • A command KaTeX does not know. KaTeX covers most of LaTeX maths mode but not all of it, and no packages can be loaded. Look the command up in KaTeX's supported functions, and write an equivalent from that list.

  • A macro defined in another formula. A \newcommand or \def works only inside the formula that defines it. Write the command out in full where it is used.

  • A display environment in an inline formula. align*, gather and a \tag need display mode. If the formula is written $$…$$ on one line, it is inline: put the $$ lines on their own lines.

    $$
\begin{align*}
a &= b + c
\end{align*}
$$

  • A link inside the formula. \href and \url are refused in maths. Put the link in the text around the formula.

See Mathematics.

A directive shows as text

You see the :::name line and the closing ::: on the page, with the body rendered between them. That means no construct claimed the name, and it is shown as you typed it rather than guessed at.

  • The name is misspelled, or is not in the vocabulary. :::theorm and :::proposition are not directives. Check the name against the syntax reference; for a statement kind the list does not have, use :::statement[Proposition].
  • A gallery with no images. :::gallery takes image lines only; with none, it stays text.
  • A printed page number that is not one. :pb[] takes an arabic or roman number (:pb[412], :pb[xii]) and nothing else.

A colon inside ordinary prose (3:1, 12:30) is never a directive and is shown as typed.

An attribute line is printed

A line such as {align=center} appears on the page instead of centring the block below it. The line is shown as text whenever it is not understood in full:

  • A typo in a key or a value: {alig=center}, {align=centre}.
  • A key that belongs on a directive's fence, such as number= or label=. Write it on the fence: :::theorem{number=3.17}.
  • A blank line between the attribute line and its block. The line must sit directly above the block.
  • The line is inside a list item or a quote, where it is text.

The keys and values are listed in the syntax reference.

An image does not open full screen

Clicking an image opens a full-screen viewer only when the viewer would show it larger than the page already does. A small image shown at its natural size has nothing to gain and stays as it is. TikZ diagrams and gallery images always open.

  • The image is inside a link. [![alt](image)](https://…) follows the link when clicked, by design.
  • The image did not load. A failed image becomes a quiet box with its alt text. Check that the address is right and publicly reachable.

A diagram shows "Diagram not rendered."

A :::tikz block is compiled when the work is saved, and the page shows the image. This placeholder means there is no image yet: the diagram has not been compiled, or LaTeX could not compile it.

  • Open the work in the editor and switch to Visual. The block compiles there and shows LaTeX's error with the line of your source it refers to.
  • A package that is not available. The error lists the packages that are. The tikzcd environment does not compile correctly yet; draw the diagram with a matrix of nodes instead.
  • A whole LaTeX document. Leave out \documentclass and \begin{document}; they are added for you.

See Draw a diagram with TikZ.

A citation stays as typed

[@knuth1974] and [@fig:setup] are shown exactly as written. That is the current behaviour: the syntax is kept but not yet resolved into an author, year or figure number. To give a source a reader can follow, use a footnote; to point at a part of the document, use an anchor and a link. See Citations and cross-references.

Line breaks disappear

A single line break inside a paragraph does not break the line: the text reflows, as in all Markdown. Leave a blank line to start a new paragraph, or end a line with a backslash to break it inside one. In poetry, use :::verse, which keeps every line.

Two hyphens became a dash

-- becomes an en dash and --- an em dash. To show hyphens as typed, as in a command-line flag, put them in inline code: `--verbose`.