Foreword
This is an informal memo on editing typst.app/docs.
The background was explained in How about a task force to generate a better documentation? by evandrojrsilva and others.This is a wiki post dual licensed under CC BY 4.0 and Apache 2.0. You can edit it and leave your name in the signature area below. (Unfortunately, this is not a real wiki. You have to sign your name manually.)
How are docs organized
-
Introductory and guide pages (aka. prose docs) live in
docs/**/*.md.
typst/docs at main · typst/typst · GitHub -
Most reference pages are generated from the doc comments in rust source code, in (rustdoc) markdown.
typst/crates/typst-library/src at main · typst/typst · GitHub -
Some parameters accept a list of values. These big lists are generated programmatically from
impl Reflect/CastInfo.Examples
Special markups
Links
-
[counter]
⇒ counter -
[`counter`]
⇒counter -
[page counter]($counter)
⇒ page counter -
[displayed]($counter.display)
⇒ displayed -
the [both parameter]($counter.display.both)
⇒ the both parameter -
[show rules]($styling/#show-rules)
⇒ show rules
Not sure if your $-link is correct? Submit a PR first, and the CI will panic if it’s wrong. (It won’t check the hash anchor and a rare edge case, though.)
Examples
The width of the page.
```example
#set page(
width: 5cm,
margin: (x: 1cm),
)
#for i in range(3) {
box(square(width: 1cm))
}
>>> Glacier displacement is influenced
>>> by a number of factors, including
>>> + The climate
>>> + The topography
>>> + The geology
<<< ...
```
The above will turn into:
The width of the page.
#set page( width: 5cm, margin: (x: 1cm), ) #for i in range(3) { box(square(width: 1cm)) } ...
You can use four backticks (````example … ````) if your example contains ```.
#set page(height: auto, width: 240pt, margin: 15pt)
Examples can have multiple pages. The block.height parameter has an instance.
Available fonts: typst-dev-assets/files/fonts at main · typst/typst-dev-assets · GitHub.
Criteria for adding examples, quoting Laurenz Mädje:
Examples—language tag
In 90% cases, you’ll use example. Nevertheless, there’re other choices.
example— show both source and previewpreview— show preview (without source)typ,sh,bash,csv, …, or empty — show source (without preview)
Additionally, args can be specified after a colon:
-
example:"Example title"(introduced in v0.14)Examples should only have titles if there are 2+ of them or if extra clarification is helpful. (source)
-
example:singleKeep only the first page, useful if you override
set page(height: auto)with an absolute length. -
example:⟨x⟩,⟨y⟩,⟨w⟩,⟨h⟩, e.g.,example:0,0,612,317.5Keep only the first page and clip it. Lengths are in
pt(points).
Highlighting
Plain inline raw created with `backticks` will be colorless.
In addition:
- Use
`{…}`to highlight in code mode, e.g.,`{none}`and`{auto}`. - Use
`[…]`to highlight in markup mode, e.g.,`[Hello #[<label>]]`and`[\u{1f600}]`.
Heading
Headings converted to kebab case will be used as their IDs.
If you want to set an ID explicitly, append { #id } to the heading:
## How to create a basic table? { #basic-tables }
If you do so, then the ID (converted to title case) will also be used in the outline (the on this page sidebar).
Quirks
Paragraphs after a list
- A
- B
Please insert a newline after the list, because otherwise the sentence will belong to the last list item.
Footnotes
Footnotes definitions should be moved to the end of the doc comment. Otherwise, it’ll appear in the middle of the document.
See detailed specifications - pulldown-cmark.
Grammar and style of writing
Typst documentation (amongst other parts of the ecosystem) follows standard American English rules for writing. Common examples are:
- “o” instead of “ou”: behavior, color
- “ze” instead of “se”: emphasize, generalize, italicize, realize
- comma after “i.e.” and “e.g.”
Special cases
- word capitalization after colon: If colon is followed by even a single full sentence, the first word after the colon must be capitalized (source). This is optional in American English, but is required by, for example, APA format[1][2].
Note that because documentation contributors are from all around the world, there are a lot of instances of the British English being used, or words and phrases that don’t sound natural in either American or British English (or both). This can be introduced with any new PR. It’s not the intention, and it can be a good idea to check for PR’s writing before it gets merged.
However, it’s always possible to create a new PR fixing some of the prior inconsistencies in wording, grammar, etc. But a ton of one or two line change PRs is very inefficient and time consuming. This is why it’s better to make batch changes that are related to a specific grammar rule or cover a big chunk of documentation (like an entire section).
Style Guide
Wrap lines at column 80, be it a doc comment in a Rust file, or text in a Markdown file. You could write the following in your .vscode/settings.json.
{
"editor.rulers": [80]
}
Notes on rust-analyzer
You could turn off rust-analyzer.checkOnSave or even disable the whole rust-analyzer extension when editing docs.
Running cargo check in the repo typically takes ~800 MiB space.
(not counting cargo doc, cargo testit, cargo build -r, cargo build, etc.)
Signature Area
What's this?
This is a wiki post. After editing, you can leave your name below.
They will turn into the Co-authored-by field in the commit’s message, if I submit it to typst/docs/dev at main · typst/typst · GitHub in the future. (It may also remain in this form forever or be submitted by someone else, however.)
If you don’t know what Co-authored-by is, just write down your name or put a link to your Forum/GitHub profile.
Y.D.X. <73375426+YDX-2147483647@users.noreply.github.com>- @Andrew first contributed on 2025-09-03