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 licensed under 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 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, 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:
It’s important that examples don’t just demonstrate something, but are also visually appealing.
Also, examples should lean toward being “more practically useful rather than theoretically pristine”.
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"(for v0.14, not released yet)If there’re multiple examples, they can be disambiguated with (optional) titles.
-
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.
Style Guide
Wrap lines at column 80. 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>- https://forum.typst.app/u/andrew/summary edited on 2025-09-03, but didn’t left a name.