Quarkdown for Science: Formulae, Bibliography, Cross-References

This is where Quarkdown shows why the comparison with LaTeX is no accident. Academic writing demands things plain Markdown fails at entirely: typeset formulae, a citable bibliography, cross-references to numbered elements, theorems and proofs. Quarkdown brings all of it — in readable Markdown notation instead of LaTeX command soup. After the data and diagrams from part 5, this is the academic supreme discipline.

TeX formulae

Mathematics is supported natively, powered by KaTeX on HTML rendering. Inline you write formulae between two $ (with whitespace around them):

Let $ \overline v = \frac {\Delta x} {\Delta t} $ be the average velocity.

An isolated formula automatically becomes a centered block equation. Multi-line formulae you wrap — analogous to code fences — with three $:

$$$
f(x) =
\begin{cases}
    0 & \text{if } x = 0 \\
    1 & \text{if } x \neq 0
\end{cases}
$$$

One important note: a block formula does not interrupt the paragraph by itself — without a blank line before it, Markdown recognizes it as inline. If you need your own commands, you define TeX macros via .texmacro.

Bibliography and citations

Quarkdown offers CSL-powered bibliography — and reads the common formats: BibTeX (.bib), CSL JSON, YAML, EndNote, RIS. You include the source with .bibliography, cite with .cite {key}:

.bibliography {references.bib} style:{apa}

Einstein's work .cite {einstein} from 1905 revolutionized physics.
These works .cite {einstein, hawking} are foundational.

Multiple keys become one combined citation. Via style you pick from the CSL repository — ieee (default), apa, chicago-author-date, nature and many more. The bibliography title is localized automatically via .doclang; heading, page break and inclusion in the table of contents you control by parameter.

Cross-references

In typesetting, you refer to figures, tables, sections and equations — by their number, not by "see above". Quarkdown does this with .ref {id}. You assign an ID via {#id}, and .ref may appear before or after the target:

Once Quarkdown is installed, see .ref {getting-started}.

## Getting started {#getting-started}

The same pattern carries over to figures (![…](…) {#logo}), tables, equations ($ E = mc^2 $ {#energy}) and code blocks (```kotlin {#main}). For headings the reference ID also becomes the HTML id attribute — handy for direct links. Cross-references work best when the targets are numbered.

Automatic numbering

The .numbering function is the central dial. It numbers headings, figures, tables, equations, code blocks and footnotes — controlled by a dictionary in which each character is a counter or fixed symbol:

.numbering
    - headings: 1.A.a
    - figures: 1.1
    - tables: 1.1

1 is decimal, a/A Latin letters, i/I Roman numerals; anything else is a fixed symbol. paged documents come with sensible defaults. Two subtleties: figures are numbered only with a (possibly empty) caption, equations only with a cross-reference ID (convention {#_} when numbered but referenced nowhere). With .numbered {key} you can even bring any custom element into a numbered series.

The paper library

The academic toolkit is rounded out by the built-in paper library, itself written in Quarkdown. Included via .include {paper}, it provides the classic LaTeX structures:

.include {paper}

.abstract
    Here goes the summary of the document.

.definition
    Let $ \Delta x $ be the change in position over an interval $ \Delta t $,
    then the average velocity is $ v = \frac {\Delta x} {\Delta t} $.

.theorem
    ...

.proof
    ...

There are .abstract, .definition, .lemma, .theorem and .proof — all titled and, as soon as you set a numbering format (definitions, lemmas, theorems, proofs), automatically numbered. Proofs end with the classic ∎ character (customizable via .proofend). You won't get more of a LaTeX feel anywhere in Markdown.

FAQ

Do I need LaTeX installed?

No. The formulae are rendered by KaTeX in the browser, the bibliography is processed by Quarkdown itself via CSL. You need no TeX distribution and no toolchain — just Quarkdown. That's the whole point: LaTeX results without LaTeX setup.

How do I keep citations consistent?

Through the bibliography's style parameter. Switching from ieee to apa reformats all citations and the reference list — you change one line, not a hundred footnotes.

Why isn't my figure numbered?

Because it's missing the caption. Quarkdown only numbers figures that have a caption — empty if need be. For equations it's analogously the cross-reference ID.