# Quarkdown for Science: Formulae, Bibliography, Cross-References

> Part 6 of the Quarkdown series: TeX formulae with KaTeX, CSL bibliography and citations, cross-references, automatic numbering and the paper library with theorems and proofs.

Source: https://www.jpkc.com/db/en/blog/quarkdown-wissenschaftliches-schreiben/

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](https://www.jpkc.com/db/en/blog/quarkdown-daten-diagramme/), this is the academic supreme discipline.

## TeX formulae

Mathematics is supported natively, powered by [KaTeX](https://www.katex.org) on HTML rendering. **Inline** you write formulae between two `$` (with whitespace around them):

```markdown
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 `$`:

```markdown
$$$
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}`:

```markdown
.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](https://citationstyles.org) 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:

```markdown
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:

```markdown
.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:

```markdown
.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.

## Further reading

The data-driven part before this is [part 5: Tables and Diagrams](https://www.jpkc.com/db/en/blog/quarkdown-daten-diagramme/). Next we switch format entirely: **presentations** — slides, interactive fragments and speaker notes. The full reference for formulae, bibliography and numbering is in the [official wiki](https://quarkdown.com/wiki).