Skip to content
IvapoPublic

About

Convert one markdown file into one typeset PDF, fully on the local machine. Rust, pulldown-cmark, embedded Typst.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

md2pdf

Convert one markdown file — or a master and the sections it names — into one typeset PDF. Everything happens on your machine: no server, no SaaS, and no LaTeX toolchain.

pulldown-cmark parses the markdown, a small emitter maps it to Typst markup, and an embedded Typst compiler produces the PDF. The fonts ship inside the binary, so the same markdown compiles to the same PDF on every machine.

Install

$ cargo install md2pdf-cli
$ md2pdf --help

The crate is md2pdf-cli and the binary it installs is md2pdf; the library it wraps is md2pdf-core, which is what you depend on to convert markdown from your own code. From a checkout instead:

$ cargo build --release
$ ./target/release/md2pdf --help

Try it

With nothing installed: ivapo.github.io/letur. The same crate compiled to WebAssembly, converting in the page — it sets out what this dialect adds to markdown, and every example on it is one click away from a PDF in your own browser, the refusals included. Nothing is sent anywhere, and there is no server to send it to. The twelve examples that page shows are fixtures here too, frozen under tests/fixtures/examples/, where core/tests/examples_test.rs compiles the nine it accepts and holds the three it refuses to the sentence they print.

Both that page and the macOS app that draws the PDF while you write it are Letur, a second front end over this crate: it converts exactly what the command converts and refuses exactly what the command refuses, in the same words. It has a repository of its own, at github.com/Ivapo/letur, with its own releases and its own bundle.

Locally, samples/showcase/ is one document that uses every construct in the dialect — every inline and block form, the abstract it opens with and the keywords beside it, captions, groups, names and cross-references, both forms of math, a diagram, footnotes, and citations against the fake bibliography beside it, under all eleven frontmatter keys, and written across six files because that is a construct too. It is the fastest way to see the whole surface set on a page:

$ ./target/release/md2pdf samples/showcase/showcase.md
$ open samples/showcase/showcase.pdf

samples/article.md is a shorter ready-made document, and the one to start from. Convert it and open the result:

$ ./target/release/md2pdf samples/article.md
$ open samples/article.pdf

Then change columns in its frontmatter from 2 to 1 and convert it again, to see the same text across the full width of the page.

samples/press-release.md is the same tool in its second look. Convert it the same way, and compare the two pages:

$ ./target/release/md2pdf samples/press-release.md
$ open samples/press-release.pdf

samples/abstract.md is the two front-matter blocks on their own: a two-column paper that opens with an abstract and the keywords under it, both set across the full width of the page above both columns. The showcase carries them too, but in a single column, where there is nothing to span. Convert it, then put template: press-release in its frontmatter and convert it again, to see the same words as a standfirst under a masthead rule with no label at all — and the terms under it keeping theirs:

$ ./target/release/md2pdf samples/abstract.md
$ open samples/abstract.pdf

samples/diagrams.md is every kind of diagram md2pdf draws, with a little text between them: flowcharts, a sequence diagram, class diagrams, a state diagram and an entity-relationship diagram, under every keyword that reaches them. In two columns, the wide ones float across the page, and the same flowchart laid out top to bottom stays in one. The showcase carries one diagram, in a single column, where nothing floats:

$ ./target/release/md2pdf samples/diagrams.md
$ open samples/diagrams.pdf

Use

$ md2pdf paper.md                 # writes paper.pdf
$ md2pdf paper.md -o report.pdf   # writes report.pdf
$ md2pdf paper.md --emit-typst    # prints the generated Typst source
$ md2pdf paper.md --fetch         # also downloads the images it names by URL
$ md2pdf --licenses               # prints what it carries, and under what terms
$ md2pdf --licenses=full          # prints the licence texts themselves

Without -o, the PDF lands at the input path with a .pdf extension.

--emit-typst prints the Typst source instead of compiling it. That output imports the look the frontmatter chose, which exists only inside the compiler's virtual filesystem, so it serves inspection rather than a standalone typst compile.

--fetch downloads the images a document names by an http or https URL. Without it md2pdf never touches the network, and such a document stops at its first URL image; see ## Images below for the limits a fetch keeps.

--licenses is the one invocation that takes no document. It prints a one-page provenance notice: what the binary carries and under what terms. --licenses=full prints the texts themselves — this program's own terms, the two font licences and the full third-party list. Both are compiled in, so both work on a binary carried anywhere; see ## Licence below.

What the markdown may contain

This release supports headings, paragraph text, the inline constructs, the block constructs, links, cross-references, citations, include markers, tables, images, captions, figure groups, abstracts, keywords, footnotes, strikethrough, math in both its forms, and diagrams:

# Introduction

Body text with *emphasis*, **strong emphasis**, ~~struck text~~, and `inline code`.

A formula in the running text, $\sum_{i=1}^{n} i = \frac{n(n+1)}{2}$, typesets as math,
and one written between double dollars is set as a block of its own:

$$
\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}
$$

A hard line break ends this line,\
and this line follows it in the same paragraph.

An [inline link](https://typst.app), a bare autolink <https://typst.app>, and
an email address at <you@example.com>.

- a bullet list
- whose second item nests one
  - like this

3. an ordered list that starts at three
4. and keeps counting

```rust
fn main() {}
```

> A block quote.

| Construct | Supported |
| --------- | :-------: |
| a table   | yes       |

: What this release carries.

![A diagram of the three steps](figures/pipeline.svg)

: The conversion pipeline, with the *emitter* in the middle. {#fig:pipeline}

As [](#fig:pipeline) shows, the emitter sits in the middle.

A claim that needs a source[^1].

[^1]: The source, at the foot of the column.

---

## Background

Text after a thematic break.

Heading levels 1 to 6 map to Typst headings of the same level. A list whose items are separated by blank lines is set with more space between them than one whose items are not, which is the distinction markdown itself draws.

A table's header row is set in bold, and its columns take the alignment the delimiter row gives them. A row with too few cells is padded with empty ones, and a row with too many loses the extra, which is what GitHub-flavoured markdown does.

A reference link works too, and an email autolink becomes a mailto: destination. Two link shapes do not: a link with an empty destination, [text](), and a link that carries a title, [text](url "a title"). Neither Typst nor the PDF can hold a title, and an empty destination has nothing to resolve to.

One shape is not a link at all. [](#name) — with nothing between the brackets — is a cross-reference to a figure or an equation you have named, and the naming section below covers it. Any link that has text is the link it has always been, whatever its destination, so [Introduction](#introduction) still points where it always did.

Strikethrough takes one tilde on each side as well as two, so ~struck~ strikes exactly as ~~struck~~ does. A single tilde with a space beside it is still a tilde.

Every other construct is an error. A block of raw HTML makes md2pdf exit with code 1 and print the construct and its line:

$ md2pdf notes.md
error: unsupported markdown construct 'raw HTML block' at line 5

That is deliberate. Dropping or flattening content would ship a PDF that lies about its source, so the tool names what it cannot yet handle. Support arrives construct by construct.

A task list, - [ ] a / - [x] b, is supported: the box replaces the bullet, drawn by the look. Two shapes are errors — a task marker in a numbered list, 1. [ ] a, since the number and the box would both claim the place in front of the item, and a list mixing task items with plain ones.

A formula takes one of two forms. $…$ sets in the running text, and $$…$$ sets as a block of its own — wherever you write it, so a $$…$$ in the middle of a sentence breaks that sentence around it, which is what the double dollars ask for. If you meant a dollar sign rather than a formula, write \$: the backslash stops the span, and the dollar reaches the page as itself.

A document that refers to its own formulas can number them, with equations: numbered in the frontmatter. The numbers run (1), (2) down the page and land on the display form only, so an inline $…$ never takes one. One $$…$$ span is one equation whatever it holds: a multi-line aligned derivation is numbered once, against its lines, rather than once per line. Put {#eq:name} after the closing $$, on the fence or on a line below it, and you can point at that formula by name, the way you point at a figure — see the section below.

A formula is LaTeX, and the dialect accepts a bounded subset of it — the Greek letters, the relations and operators, sums, products and integrals, \frac, \sqrt, \binom, \left/\right, the accents, the font commands, the named operators, and the matrix, pmatrix, bmatrix, vmatrix, cases and aligned environments. A command outside that list is an error naming the command and its line, rather than a formula that quietly loses part of itself:

$ md2pdf paper.md
error: math error at line 12: unsupported command '\text'

Two things that follow from it. \text{…} is not on the list yet, so prose inside a formula is written beside it instead — $100\%$ of the sample rather than $100\% \text{ of the sample}$. And a % inside a formula must be written \%, because LaTeX reads a bare one as a comment and would drop the rest of the line.

The formula is LaTeX and not Typst's own math syntax, which matters because Typst's is close enough to look like it should work: $frac(a,b)$ is not an error, it just sets as the letters f r a c (a, b). Write $\frac{a}{b}$.

Body text reaches the PDF verbatim. Characters that Typst would otherwise interpret are escaped for you, so a $5 that markdown does not read as a formula stays five dollars:

\  #  $  *  _  `  @  <  >  [  ]  ~  -  +  =  /

Code reaches the PDF verbatim too, by a different route: its content travels as a string rather than as markup, so nothing inside a pair of backticks or a fence is escaped and nothing needs to be. `` #5 $5 \ `x` `` prints exactly those characters. A fence's language tag is carried through, so Typst highlights the block — except mermaid, which draws the diagram instead (see Diagrams). A link's destination takes that same route, so a # fragment in a URL arrives intact.

Images

An image points at a file that travels with the document:

![The three steps, drawn as boxes](figures/pipeline.svg)

A small icon ![a check mark](check.svg) sits inside this sentence.

The path is relative to the markdown file that names it, and md2pdf reads the file from there — in a document written across several files, that is the section the image was drawn in and not the master. An image alone in its paragraph is set as a block and scales down to the column; an image with text beside it stays in the line. Eight formats work, and the extension decides which one a file holds:

png  jpg  jpeg  gif  webp  svg  svgz  pdf

The text in the square brackets is alt text. It reaches the accessibility layer of the PDF rather than the page, so it is never used as a caption. There is no syntax for a width, a rotation or a crop; the image takes its natural size, bounded by the column.

An image alone in its paragraph can carry a caption, which is what turns it into a numbered figure. The next section covers that, for a table and a code block as well.

A file that md2pdf cannot read is an error that names the path, the line that asked for it, and the reason:

$ md2pdf paper.md
error: cannot read figures/pipeline.svg for the image at line 12: No such file or directory (os error 2)

Bytes that disagree with their extension are an error too. So are three destinations: any URI scheme other than http or https, a data: URI included; an absolute path, which converts on one machine only; and a path that leaves the document's own folder.

An http or https URL is accepted as an image's name. The library fetches nothing, and a program that embeds it supplies the image's bytes under the URL. md2pdf fetches only when asked, so a document from anywhere reaches the network only when you decide it should:

$ md2pdf paper.md
error: no image fetched for 'https://example.com/figures/plot.png' at line 7
hint: pass --fetch to download images named by a URL

Under --fetch, each distinct URL is downloaded once, within fixed limits: 30 seconds and 20 MB per image, at most ten redirects, and only a 2xx answer counts. The format is read from the bytes, never from the URL's ending, so an HTML error page served where an image should be is refused naming the URL. Nothing is cached or written to disk, and a fetch goes through any proxy the environment names. A fetch that fails names the URL, the line and the reason:

$ md2pdf paper.md --fetch
error: cannot fetch https://example.com/figures/plot.png for the image at line 7: 404 Not Found

That last one is about where a path lands, not about the .. written in it. A document and the files it names travel as one folder, so ../../plot.svg climbs out of that folder and is refused wherever it is written. ../figures/plot.svg written inside sections/method.md does not: it means figures/plot.svg, beside the master, and it converts.

Several files

A document long enough that one file has stopped being comfortable can be written as several. A master carries the frontmatter and names its sections in the order they are read:

---
title: A Long Report
author: Iva Po
figures: sectioned
---

[](sections/introduction.md)

[](sections/method.md)

[](sections/results.md)

The sections are ordinary markdown files with no frontmatter of their own:

$ md2pdf report.md          # writes report.pdf, out of all four files

A link with no text pointing at a .md file is an include, and it has to be a paragraph of its own. That is the same shape a cross-reference uses — [](#fig:one) — and the empty text is what makes it one. A link that carries text is an ordinary link whatever it points at, so [the method](sections/method.md) still links.

It is one document, not three PDFs stapled together. The files are joined before anything is parsed, so a figure declared in the first is Figure 1.1, a [](#fig:it) in the third reads its number, and a footnote defined anywhere lands at the foot of the column that cites it. Numbering, references, footnotes and citations run continuously because nothing in the pipeline was ever written against a file.

Only the master carries frontmatter. That is what makes the title, the look, the column count, the numbering scheme and the bibliography one set of answers rather than several to reconcile. A section that opens with a --- line is an error naming that file, and so is a section that names a section of its own — the master is the one place the order lives.

Every error names the file you wrote it in:

$ md2pdf report.md
error: math error in sections/method.md at line 12: unsupported command '\includegraphics'

A section's neighbours are its own. An image named inside sections/method.md is looked for beside that file, so ![A figure](figure.png) there means sections/figure.png. A chapter folder holding its own figures can be moved, copied or shared whole — moving it means editing one line, the master's marker, which is the line that exists to say where a section is.

And a section can still reach the figures the whole document shares. ../ in a section climbs out of that section's folder and not out of the document, so ![A plot](../figures/plot.svg) in sections/method.md finds figures/plot.svg beside the master. A chapter folder keeps what is only its own and names what is everyone's:

report.md               <- the master
figures/plot.svg        <- shared: ../figures/plot.svg from any section
sections/method.md
sections/figure.png     <- the chapter's own: figure.png from method.md

Captions

A paragraph of its own beneath an image, a table or a code block, opening : , is that block's caption:

![The three steps, drawn as boxes](figures/pipeline.svg)

: The conversion pipeline, with the *emitter* in the middle.

| Construct | Counter |
| --------- | :-----: |
| a table   | its own |

: The constructs and the counters they keep.

```rust
fn main() {}
```

: The entry point.

A caption is what makes a figure. A block with one is set as a numbered figure — Figure 1, Table 1, Listing 1 — and each kind counts on its own, so inserting a table above a listing does not renumber the listing. Typst renumbers them all whenever anything moves, and the caption sets beneath. A block without a caption is the plain block it has always been: it takes no number and consumes none, so a document written before this release typesets exactly as it did. The caption is ordinary markdown, so emphasis, code, links and formulas all work inside one. The words "Figure", "Table" and "Listing", the number's format and the punctuation after it belong to the look, so the two bundled ones differ.

Leave the blank line above a caption. Above an image it is required: without it the two are one paragraph, and the image stays in the line with : printed as text beside it. Above a table it is required too, because markdown reads a non-blank line after the last row as one more row, so the marker lands in a cell. Above a code block it is optional, since a fence ends at its closing fence — but one rule for all three is easier to keep than three.

Only a standalone image takes a caption; an image inside a sentence is not a figure. A : paragraph anywhere else — after prose, after a heading, after a list — is ordinary text, unchanged. Two things are errors, each naming the line: a : with nothing after it, and a second caption under one block.

Diagrams

A fenced block tagged mermaid is drawn as the diagram it describes — the same spelling GitHub and GitLab draw, so the file reads the same way there:

```mermaid
flowchart LR
    md[Markdown source] --> parse[pulldown-cmark parses]
    parse --> emit{Emitter maps events}
    emit -->|Typst markup| pdf[(PDF)]
```

: The pipeline, drawn. {#fig:pipeline}

As [](#fig:pipeline) shows, the emitter sits in the middle.

Five kinds are drawn in this release: flowcharts (flowchart or graph), sequence diagrams (sequenceDiagram), class diagrams (classDiagram or classDiagram-v2), state diagrams (stateDiagram or stateDiagram-v2) and entity-relationship diagrams (erDiagram). Any other kind is an error naming the keyword you wrote and its line, as is a syntax error inside the block. Everything is drawn on your machine, inside md2pdf, with no browser and no network.

A caption makes it a figure, exactly as it does for an image: numbered with the images, Figure 1, and referenceable by the name its caption declares. Without one it is a plain diagram with no number.

How big a diagram is, the look decides. Its labels set at the size of the look's captions (9 pt in article, 9.5 pt in press-release), and a diagram is never enlarged. One too wide for its column at that size stays in the column while shrinking it keeps its labels at 8 pt or more; past that, a captioned diagram floats across the whole page, and one wider than the page shrinks to fit it. So a long left-to-right chain gets small: in article, a chain of four-word labels sets at about 9 pt page-wide at four nodes and 5 pt at eight. If a diagram comes out too small, lay it out top to bottom — flowchart TB in place of flowchart LR — which keeps the same chain one column wide.

The look owns how a diagram looks, so a block may not carry its own configuration: a %%{init: …}%% directive anywhere in it, or YAML front matter opening it, is an error. %% comments are fine. A diagram stands at the top level of a file, not inside a list item, a block quote, a footnote or a figure group.

To show Mermaid source as code rather than draw it, tag the fence anything else — ```text or ```mmd — and it sets as a listing, as it always has. The tag must be exactly mermaid, lowercase: ```Mermaid is a listing too.

Figures with more than one member

Two images side by side, under one caption and one number, are a group. Wrap them in a pair of ::: lines and put the caption last, just above the closing one:

:::

![The first step](figures/one.svg)

![The second step](figures/two.svg)

: The two halves of the pipeline. {#fig:halves}

:::

That is Figure 1 once, not twice — the members share the caption, the number and the name, so [](#fig:halves) points at the pair. A group takes the three things a caption takes: a standalone image, a table and a code block. Write as many as you like; they sit in one row, and how far apart is the look's business.

md2pdf reads two words after the opener, and every other one is yours. abstract and keywords are those words, and each opens something else entirely — see The abstract a paper opens with and The keywords a paper is indexed by, below. ::: figure and ::: table are both fine and both mean the same thing, because a group's kind comes from what the members are — two tables are a Table whatever you opened them with.

::: at the start of a paragraph is reserved. Everywhere else it is ordinary text: inside a sentence, on the second line of a paragraph, and inside a code block, which is how the example above is written. Leave the blank lines in — a ::: and the image under it with no blank line between them are one paragraph, not a group, and md2pdf says so rather than guessing.

Ten things are errors, each naming the line: a group with no caption, one with no member, a second : line, a : line with a member after it, a group inside a group, an abstract inside a group, keywords inside a group, a group you never close, a paragraph starting ::: that is neither an opener nor a closer, and anything between the members that is not one of the three:

$ md2pdf paper.md
error: unsupported markdown construct 'figure group with no caption' at line 12

The abstract a paper opens with

An abstract is set across the full width of the page, above the columns the body runs in. It is the same ::: delimiter, with one of the two words md2pdf reads after the opener, and it goes in the document's front matter — above anything else it says:

---
title: A Paper That Opens With an Abstract
author: Iva Po
---

::: abstract

An abstract is the one block a paper opens with that is neither a section, nor a
figure, nor body text. Write as many paragraphs as it takes.

:::

# Introduction

The block holds paragraphs, and the inline constructs inside them: emphasis, strong, code, links, footnotes and an inline $…$ formula. That is enough for a structured abstract, which is written as bold run-in text — Background. then Methods. then Results. — rather than as headings.

It takes no caption, no name and no number, and it restarts nothing: it is not a figure, so it cannot perturb figures: sectioned, and it is not a heading, so it takes no section number under headings and never appears in the document's outline.

The look decides what it looks like. The article look gives it a centred Abstract label and sets it narrower than the page; press-release sets the same words as a standfirst under the masthead rule and prints no label at all, because a press release has a lede rather than an abstract. samples/abstract.md is the same document in both.

It has to stand in the front matter, and there may be only one. Both looks lift it out of the flow, so an abstract written lower down would appear at the top anyway and the page would disagree with the file you wrote. The keywords block below is the other thing the front matter may hold, and the order between the two is yours; what is refused is body content above either. In a document written across several files, the front matter is the front matter of the joined stream — so the abstract may be a section file of its own that the master names before the rest.

Nine things are errors, each naming the line: a second abstract, one with body content above it, one opened inside a list item, a block quote or a footnote definition, a block inside it that is not a paragraph — including a standalone image — a display equation or a citation inside it, keywords inside it, an empty one, a : caption line inside it, and one you never close:

$ md2pdf paper.md
error: unsupported markdown construct 'abstract that is not the document's first block' at line 24

That message says first block because body content above an abstract does mean it is not the first one. A keywords block above it is not body content, and does not reach this.

The keywords a paper is indexed by

The terms a paper is indexed by are the other thing the front matter may hold. It is the same ::: delimiter with the other word md2pdf reads, holding one paragraph whose terms are separated by ;:

::: keywords

typesetting; markdown; figure numbering, sectioned

:::

The separator is ; because a keyword may hold a comma — figure numbering, sectioned does. That is the same reason author and affiliation take ; in the frontmatter, so if you have written one of those you have already met it.

A term is plain text. Emphasis, strikethrough, inline code, a link, a formula, a footnote, an image, a citation and a hard break are each named at the line you wrote them on, because a ; standing inside any of them is a semicolon you never wrote as a separator and the split would break a term at it.

The look decides what the terms look like, down to the character between two of them. md2pdf hands the look a list and never a sentence: the article look sets them under the abstract at the same measure with a bold-italic Keywords: run-in, and the press release sets them under its standfirst with the same label. Neither look refuses them. And the block takes none of a figure's machinery — no number of its own, and no counter it restarts — so a figures: sectioned document numbers its first table 1.1 with or without one.

Nine things are errors, each naming the line: a second keywords block, one with body content above it, one opened inside a list item, a block quote or a footnote definition, a block inside it that is not a paragraph, a second paragraph inside it, any of the nine constructs above, an empty term or an empty block, a : caption line inside it, and one you never close:

$ md2pdf paper.md
error: unsupported markdown construct 'inline code inside keywords' at line 31

Naming a figure or an equation, and pointing at it

End a caption with {#name} to name the figure it makes, then write [](#name) to point at it:

![The three steps, drawn as boxes](figures/pipeline.svg)

: The conversion pipeline. {#fig:pipeline}

As [](#fig:pipeline) shows, the emitter sits in the middle.

That reads "As Figure 1 shows…" on the page, and it stays true. Insert another figure above it and the sentence reads "As Figure 2 shows…" without your touching it, which is the whole reason to number anything. The name never appears in the PDF; the supplement and the number come from the look, as the caption's own type does.

The brackets must be empty. [](#name) is a reference; [the diagram](#name) is an ordinary link, and so is [ ](#name), whose text is a space rather than nothing. That is what keeps [Introduction](#introduction) and every other anchor link meaning what it always meant.

A name may hold letters, digits, -, _, : and ., and may not begin with : or .. The fig:, tab: and lst: prefixes are a convention and nothing more — the kind comes from what the caption sits under, so {#pipeline} on an image is a figure and so is {#tab:pipeline}. Names beginning fn- followed by digits are reserved for footnotes.

Six things are errors, each naming the line: a reference to a name nothing declares, the same name declared twice, a character outside the set, a reserved name, a reference to an equation in a document that did not number its equations, and a {#name} group that is a paragraph of its own with nothing above it to name. A name is checked here rather than left to the typesetter, which would otherwise report a name you never typed and no line at all:

$ md2pdf paper.md
error: name error at line 24: nothing declares the name 'fig:piepline'

A display equation is named after its closing fence, since it has no caption line to carry a name — on the fence itself, on the line below it, or in the paragraph below that:

$$
a^2 + b^2 = c^2
$$ {#eq:pythagoras}

As [](#eq:pythagoras) shows, the two shorter sides settle the longest one.

That reads "As Equation 1 shows…". The group has to be the whole of what follows the closing $$ — $$…$$ {#eq:one} and more is the prose it looks like — or the whole of a line below it, with nothing but blank lines between the fence and the name. An inline $…$ takes no name, because only the block form is ever numbered.

Pointing at an equation needs equations: numbered in the frontmatter, and md2pdf says so with your line if you forget:

$ md2pdf paper.md
error: name error at line 24: 'eq:pythagoras' names an equation, and a document that
points at one must set 'equations: numbered'

Naming one is always fine — it is only the reference that needs the key, because an unnumbered equation has no number for the sentence to say.

Footnotes

A reference in the text puts its note at the foot of the column that holds it:

A claim that needs a source[^src], and the same source again[^SRC].

[^src]: The note itself, which may hold *emphasis*, `code` and a second
    paragraph.

The definition may sit anywhere in the file, above or below the reference. A label is matched without regard to case, so [^SRC] and [^src] are one note, and the numbers are Typst's: they run in the order the notes appear on the page, and a note cited twice carries one number.

Three shapes are errors. A definition that no reference cites would reach no page. A second definition for one label would lose a body. A reference inside a definition would put a footnote inside a footnote. A reference whose definition is missing altogether is not an error: it stays on the page as the text you typed, the way an unresolved link reference does.

Citing sources

Name a bibliography file in the frontmatter and cite a key with [@key] — or with [+@key] for a citation that reads in the sentence, [-@key] for the year alone, and [@a; @b] for two sources in one parenthesis. The reference list is set at the end of the document:

---
title: Citing a source
bibliography: refs.yml
---

Typesetting was rethought from the ground up [@DBLP:books/lib/Knuth86a].

The file sits beside the document, as an image does, and it is the author's own — either a Hayagriva .yml/.yaml file or a BibLaTeX .bib one, both of which Typst reads directly:

"DBLP:books/lib/Knuth86a":
  type: book
  title: "Computers and Typesetting, Volume A: The TeXbook"
  author: Knuth, Donald E.
  date: 1986
  publisher: Addison-Wesley

The marks are numbered, [1], unless the frontmatter says citations: author-date, under which a sentence written As [+@knuth1986] showed, the method holds [@lamport1994] reads As Knuth (1986) showed, the method holds (Lamport, 1994) and the list is alphabetical. The mark is Typst's; the look decides which author-date style answers the key, and what the label above the list says and how it is set. Nothing is fetched: no key is resolved against anything on the network. The file is read for its keys before anything is typeset, so a key it does not hold is named where you cited it rather than reported by the compiler.

The brackets are required. A bare @key is not a citation, because an unbracketed @ is load-bearing in ordinary text — an email address is the everyday case — so a@b.com and @thing reach the page as you typed them, and so do [see @k] and [a@b.com].

Eight things are errors, and each names the line you wrote it on. Four are about the citation: Pandoc's locator [@k, p. 33] is not in this dialect and is named rather than guessed at; a form on a group, [+@a; @b], is refused because a form names one source; a piece that is not a key, [@a; b], is refused rather than written into the call; and a citation in a document that names no bibliography is an error rather than text on the page:

error: citation error at line 7: '@smith2020' is cited and the frontmatter names no bibliography

Two more are about the keys. A key the bibliography does not hold is one:

error: citation error at line 7: '@smith2020' is cited and the bibliography does not hold it

and so is a name your document and your bibliography both use, because Typst's labels are one namespace. Naming a figure {#smith2020} beside a bibliography holding smith2020 is fine on its own; it is [](#smith2020) that has no way to mean one of them rather than the other:

error: citation error at line 12: 'smith2020' names something in this document and a key in the bibliography, and one reference cannot mean both

The last two are about the file, and both name the frontmatter line that declared it: a bibliography that does not parse, and one whose extension is neither .yml, .yaml nor .bib.

Frontmatter

A leading --- block controls the layout. It takes eleven keys, all optional:

---
title: A Minimal Example
author: Iva Po^1; Someone Else^2      # ';' separates them, '^' points at an affiliation
affiliation: Anthropic; MIT           # ';' separates them too
date: 10 August 2026        # a free string, typeset as you wrote it
template: article           # article or press-release
columns: 1                  # 1 or 2
equations: numbered         # numbered or plain
figures: sectioned          # sectioned or flat
headings: 2                 # plain, or a depth from 1 to 6
citations: author-date      # numeric or author-date
bibliography: refs.yml      # a Hayagriva .yml/.yaml or BibLaTeX .bib file
---

template picks the look:

Name The look Columns without a columns key
article the default: a centred title block, the affiliations under the authors 1
press-release a dateline above a flush-left title, over a rule 1

Both looks set a single column unless the document says columns: 2, and a columns key of your own always wins.

author takes several names, separated by ; — never a comma, because Po, Iva is an ordinary way to write one person's name. A ^ after a name points at an affiliation, and affiliation is a ;-separated list too, numbered from 1 in the order you wrote it:

author: Iva Po^1; Someone Else^2; A Third Person^1, 2
affiliation: Anthropic, San Francisco; MIT, Cambridge

There is no authors and no affiliations — one key, several values. The count decides how much you have to say. Write no affiliation at all and the markers are dropped, so a file you are still drafting converts rather than stopping. With exactly one, the markers are optional and every author belongs to it. From two up an affiliation nobody points at is an error, and so is a marker pointing at one you did not write. A marker that is not a number, an empty entry in either list, and a ^ with no name before it are errors whatever you wrote — those are typing mistakes, not relations. An author with no marker beside authors that have one is fine: a fourth author from no lab is a real document.

date is your text and nothing else. md2pdf never reads a clock, so the same file makes the same PDF on every machine and on any day.

equations: numbered numbers the document's display formulas, (1), (2), down the page, and is what lets a sentence point at one by name. plain is the default, so a file that says nothing gets no numbers and reads exactly as it did before. You say whether; the look says how — the format, and where on the line it sits. Both bundled looks write (1).

figures: sectioned gives a figure, a table and a listing the number of the section it stands in — Figure 1.1, Table 1.2, Table 2.1 — restarting each kind at every # heading and at no other level. Whether the headings themselves carry numbers is the next key's question, and the two are independent. flat is the default, one counter per kind down the whole document, so a file that says nothing reads exactly as it did before. You say whether; the look says how, as with equations. A reference reads whatever the caption reads, so [](#tab:one) says Table 1.1 in a sectioned document. A display equation is not a figure: under equations: numbered it keeps its (1) and takes no section.

headings: 2 numbers the headings down to the second level — 1 First, 1.1 Background, 2 Second — and leaves a ### and everything below it unnumbered. The value is the deepest level that carries a number, 1 to 6; plain is the default, so a file that says nothing gets no heading numbers and reads exactly as it did before. There is no numbered: 6 is how you say it, and the depth is the part a yes-or-no key cannot express. You say how deep; the look says how — the separator, the format, and where the number sits. The two numbering keys compose: under figures: sectioned and headings: 2 a document reads 1.1 Background and Table 1.2 on the same page.

citations: author-date makes every mark name its source — Knuth (1986) in a sentence, (Knuth, 1986) in a parenthesis — and sets the reference list alphabetically. numeric is the default, so a file that says nothing gets the [1] it always did, with the list in cited order. You say whether the marks name their authors; the look says how — which author-date style answers, and both bundled looks answer with Harvard cite-them-right.

Without title, author, affiliation and date together, the PDF gets no title block. Without the frontmatter altogether, it gets every default.

A key outside the eleven, a columns value other than 1 or 2, or a template, equations, figures, headings or citations value outside its set, is an error that names the key and its line:

$ md2pdf paper.md
error: frontmatter error at line 3: unknown key 'subtitle'
$ md2pdf release.md
error: frontmatter error at line 3: key 'template' takes article or press-release, not 'ieee'

The block is a small YAML subset, not full YAML: one key: value pair per line, blank lines and # comments skipped, and one pair of quotes stripped from a value. Nesting and lists are errors.

Styling

A look owns all styling: the page setup, the text font, the code font, the heading style, the rule a thematic break draws, the title block, and the column count. Two ship — core/assets/template.typ is article and core/assets/press-release.typ is press-release. Change one of those files to change how its look reads. The parser and the emitter do not need to know.

A third look is a third .typ file plus one name in core/src/frontmatter.rs. It has one contract to meet: export template, divider, abstract, keywords and diagram, and let template take title, author, affiliation, columns, date, equations, figures, headings and citations before its trailing document argument. md2pdf names all nine on every call, and imports abstract, keywords and diagram separately, each for a document that has one. author arrives as an array of (name, markers) dictionaries and affiliation as an array of strings: what crosses is the relation between the two lists, and every question of how it looks — that a marker is a superscript, that the names run on one line — is the look's own.

Everything else a look decides, it decides over Typst's own elements with show and set rules, taking no argument at all. A table's header row, a code block's font, a figure's caption, the space between a group's members and how far off the margin a block of code sits all reach a look that way — which is why neither a caption nor a group widened the call at all. Neither front-matter block does either: they are the third and fourth exported names beside divider, not arguments. diagram is the fifth, and the one place a caption crosses into a look: whether a diagram floats across the page depends on its width against the page, so the look builds that figure itself, around the caption and the name it is handed. An argument is added only where the author has something to ask for, which is what equations, figures, headings and citations are: the four questions a look cannot answer on its own, because the answer is a fact about the document rather than about the house style.

Licence

The code in this repository is MIT; LICENSE carries the text, and it travels inside both published crates. The binary carries all of it too: md2pdf --licenses=full prints that text, the two font licences below and THIRD-PARTY-LICENSES.md, all compiled in, so someone handed the executable alone has the terms without needing this repository. md2pdf --licenses on its own prints the short version — a one-page notice naming what is bundled and under which licence, with the crate graph in a paragraph.

What the binary embeds, and under what terms. md2pdf is statically linked: the Typst compiler is not a runtime dependency you install separately but code compiled into the executable, so its licence follows the binary wherever it goes. Typst and its crates, and mitex, are Apache-2.0, and merman, which draws the diagrams, is MIT or Apache-2.0. Almost everything else is permissive too — MIT, BSD, Zlib, Unicode-3.0 and the rest. Four crates are MPL-2.0, which is copyleft per file: cssparser, cssparser-macros, dtoa-short and selectors, which merman's HTML sanitiser brings. They are compiled in unmodified, their source is on crates.io under the name and version the list gives each, and their terms reach those files and nothing around them. THIRD-PARTY-LICENSES.md is the full list, 379 crates with the text of every licence among them, generated from the resolve by tools/third-party-licenses.py and shipped in both crates.

The fonts are bundled too, and are not crates. Most are under the SIL Open Font Licence — Libertinus Serif in four faces for body text, and Libertinus Mono for code; see core/assets/fonts/OFL.txt. The math font, NewCMMath-Regular, is under the GUST Font Licence; see core/assets/fonts/GUST-FONT-LICENSE.txt. Both files travel in the published crate beside the fonts they cover.

Typst is a trademark of its authors. This project uses the name to say what it is built on, which is what Apache-2.0 §6 leaves to nominative use; it is not affiliated with or endorsed by them.

About

Convert one markdown file into one typeset PDF, fully on the local machine. Rust, pulldown-cmark, embedded Typst.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages