Tidy

Keep your code tidy.

v0.4.3 April 26, 2025

https://github.com/Mc-Zen/tidy

Mc-Zen

Abstract
tidy is a package that generates documentation directly in Typst for your Typst
modules. It parses doc-comments and can be used to easily build a reference
section for each module.

Contents
I Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
II More options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
III Accessing user-defined symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
IV Preview examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
IV.a Standalone usage of example previews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
V Customizing the style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
V.a Customizing Colors (mainly for the default style) . . . . . . . . . . . . . . . . . . . . . 9
V.b Predefined styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
VI Help command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
VI.a Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
VI.b Searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
VI.c Output customization (for end-users) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
VI.d Notes about optimization (for package developers) . . . . . . . . . . . . . . . . . . 13
VII Doc-comment testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
VIII Function documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

1
I Introduction
You can easily feed tidy your in-code documented source files and get beautiful documentation of all
your functions and variables printed out. The main features are:
• Type annotations,
• seamless cross references,
• rendering code examples (see Section IV),
• help command generation (see Section VI), and
• doc-comment testing (see Section VII).
First, we import tidy.

1 #import "@preview/tidy:0.4.3" typ

We now assume we have a Typst module called repeater.typ , containing a definition for a function
named repeat() .

repeater.typ
1 /// Repeats content a specified number of times. typ
2 /// -> content
3 #let repeat(
4 /// The content to repeat. -> content
5 body,
6
7 /// Number of times to repeat the content. -> int
8 num,
9
10 /// Optional separator between repetitions of the content. -> content
11 separator: []
12 ) = ((body,)*num).join(separator)
13
14 /// An awfully bad approximation of pi.
15 /// -> float
16 #let awful-pi = 3.14

Tidy uses /// doc-comments for documentation. A function or variable can be provided with a
description by placing a doc-comment just before the definition.
Until type annotations are natively available in Typst, a return type can be annotated with the ->
syntax in the last line of the description. If there is more than one possible return type, the types can
be given separated by the pipe | operator, e.g., -> int | float .
Function arguments are documented in the same way. All descriptions are parsed as Typst markup.
Take a look at Section III on how to add images or examples to a description.
Calling parse-module() will read out the documentation of the given string (for example loaded from
a file). We can then invoke show-module() on the returned docs object. The actual output depends
on the utilized style template, see Section V.

1 #let docs = tidy.parse-module(read("docs.typ"), name: "Repeater") typ

2 #tidy.show-module(docs)

2
This will produce the following output.

Repeater
• repeat()
Variables
• awful-pi

repeat
Repeats content a specified number of times.
Parameters
repeat(
body: content ,
num: int ,
separator: content
) -> content

body content

The content to repeat.

num int

Number of times to repeat the content.

separator content

Optional separator between repetitions of the content.

Default: []

awful-pi float

An awfully bad approximation of pi.

Cool, he?
By default, an outline for all definitions is displayed at the top. This behaviour can be turned off with
the parameter show-outline of show-module() .
There is another nice little feature: in the doc-comment, you can cross-reference other definitions with
the standard Typst syntax for referencing objects, e.g., @repeat or @awful-pi . This will automati-
cally create a link that when clicked in the PDF will lead you to the documentation of that definition.
Parameters of functions can be referenced as @repeat.num .
Of course, compilation happens almost instantaneously, so you can see the live result while writing
the docs for your package. Keep your code documented!

II More options
Sometimes you might want to document “private” functions and variables but omit them in the
public documentation. In order to hide all definitions starting with an underscore, you may set
omit-private-definitions to true in the call to show-module() . Similarly, “internal” parameters

3
of otherwise public functions can be concealed by naming them with a leading underscore and setting
omit-private-parameters to true as well.

III Accessing user-defined symbols

This package uses the Typst function eval() to process function and parameter descriptions in order
to enable arbitrary Typst markup within those. Since eval() does not allow access to the filesystem
and evaluates the content in a context where no user-defined variables or functions are available, it is
not possible to directly call #import , #image or functions that you define in your code.
Nevertheless, definitions can be made accessible with tidy by passing them to parse-module()
through the optional scope parameter in form of a dictionary:

1 #let make-square(width) = rect(width: width, height: width) typ

2 #tidy.parse-module(
3 read("my-module.typ"), scope: (make-square: make-square)
4 )

This makes any symbol in specified in the scope dictionary available under the name of the key. A
function declared in my-module.typ can now use this variable in the description:

1 /// This is a function typ

2 /// #make-square(20pt)
3 #let my-function() = {}

It is even possible to add entire modules to the scope which makes rendering examples using your
module really easy. Let us say the file wiggly.typ contains:

wiggly.typ
/// Draw a sine function with $n$ periods into a rectangle of given
1 typ
size.
2 ///
3 /// *Example:*
4 ///
5 /// ```example
6 /// #draw-sine(1cm, 0.5cm, 2)
7 /// ```
8 ///
9 /// -> content
10 #let draw-sine(
11
12 /// Height of bounding rectangle. -> length
13 width,
14
15 /// Width of bounding rectangle. -> length
16 height,
17
18 /// Number of periods to draw.
19 ///
20 /// Example with many periods:
21 /// ```example

4
 22 /// #draw-sine(4cm, 1.3cm, 10)
23 /// ```
24 /// -> int | float
25 periods
26 ) = box(width: width, height: height, {
27 let resolution = 100
28 let frequency = 1 / resolution * 2 * calc.pi * periods
29 let prev-point = (0pt, height / 2)
30 for i in range(1, resolution) {
31 let x = i / resolution * width
32 let y = (1 - calc.sin(i * frequency)) * height / 2
33 place(line(start: prev-point, end: (x, y)))
34 prev-point = (x, y)
35 }
36 })

Note, that we use the predefined example language here to show the code as well as the rendered
output of some demo usage of our function. Options for previewing code examples are treated more
in-detail in Section IV.
We can now parse the module and make the module wiggly available through the scope parameter.
Furthermore, we apply another trick: by specifying a preamble , we can add code to run before each
example. Here we use this feature to import everything from the module wiggly . This way, we can
directly write draw-sine(...) in the example (instead of wiggly.draw-sine(...) ):

1 #import "wiggly.typ" // don't import something specific from the module! typ
2
3 #let docs = tidy.parse-module(
4 read("wiggly.typ"),
5 name: "wiggly",
6 scope: (wiggly: wiggly),
7 preamble: "#import wiggly: *\n"
8 )

In the output, the preview of the code examples is shown next to it.

wiggly
draw-sine
Draw a sine function with 𝑛 periods into a rectangle of given size.
Example:

#draw-sine(1cm, 0.5cm, 2)

Parameters
draw-sine(
width: length ,
height: length ,

5
 periods: int float
) -> content

width length

Height of bounding rectangle.

height length

Width of bounding rectangle.

periods int or float

Number of periods to draw.

Example with many periods:

#draw-sine(4cm, 1.3cm, 10)

IV Preview examples
As we already saw in the previous section, a function, variable, or parameter description can contain
code examples that are automatically rendered and displayed side-by-side with the code.
For this purpose the two raw languages example (for Typst markup mode)

1 /// ```example typ

2 /// #sinc(0)
3 /// ```

and examplec (for Typst code mode)

1 /// ```examplec typ

2 /// sinc(0)
3 /// ```

are available in all doc-comments. In both versions, you can insert hidden code lines starting with >>>
anywhere in the demo code. These lines will just be executed but not displayed.

1 /// ```examplec typ

2 /// >>> import my-math: sinc // just executed, not shown
3 /// sinc(0)
4 /// ```

This is useful for many scenarios like import statements, wrapping everything inside a container of a
fixed size and other things.
Conversely, lines starting with <<< will only be shown but not executed.

6
As an alternative, the function example() provides some bells and whistles which are showcased
with the following example-demo.typ module which contains a function for highlighting text with
gradients¹:

flashy
/// #example(`#example-demo.flashy[We like our code flashy]`)

#example-demo.flashy[We like our code flashy]

We like our code flashy

/// #example(`#example-demo.flashy[Large previews will be scaled automatically to fit]`)

#example-demo.flashy[Large previews will be

scaled automatically to fit] Large previews will be scaled automatically to fit

/// #example(`#example-demo.flashy[Change code to preview ratio]`, ratio: 2)

#example-demo.flashy[Change code to preview ratio]

Change code to preview ratio

/// #example(`#example-demo.flashy(map: color.map.vlag)[Huge preview]`, scale-preview: 200%)

#example-demo.flashy(map: color.map.vlag)[Huge
preview]
Huge preview
/// #example(`#flashy[Add to scope]`, scope: (flashy: example-demo.flashy, i: 2))

#flashy[Add to scope #i ...]

Add to scope 2 …

/// #example(`Markup *mode*`, mode: "markup")

Markup *mode*
Markup mode

/// #example(`e^(i phi) = -1`, mode: "math")

e^(i phi) = -1
𝑒𝑖𝜑 = −1

/// #example(`#example-demo.flashy(map: color.map.crest)[Very extremely long examples might

maybe require the need of vertical layouting]`, dir: ttb)

#example-demo.flashy(map: color.map.crest)[Very extremely long examples might maybe require the

need of vertical layouting]

Very extremely long examples might maybe require the need of vertical layouting

Parameters
flashy(
body: content ,
map: array
) -> content

¹which seems not very advisable due to the poor readability.

7
IV.a Standalone usage of example previews
The example preview feature can also be used to add self-compiling code examples independently of
tidy. For this, tidy provides the function render-examples() .

1 #import "@preview/tidy:0.4.3": render-examples typ

2 #show: render-examples
3
4 ```example
5 #
6 ```

It also features a scope argument, that can be pre-set:

1 #show: render-examples.with(scope: (answer: 42)) typ

2
3 ```example
4 #answer
5 ```

Furthermore, the output format of the example can be customized through the parameter layout of
render-examples . This parameter takes a function with two positional arguments: the raw element
and the preview.

1 #show: render-examples.with( typ

2 layout: (code, preview) => grid(code, preview)
3 )

8
V Customizing the style
There are multiple ways to customize the output style. You can
• pick a different predefined style template,
• apply show rules before printing the module documentation or
• create an entirely new style template.
A different predefined style template can be selected by passing a style to the style parameter:

1 #tidy.show-module( typ
2 tidy.parse-module(read("my-module.typ")),
3 style: tidy.styles.minimal,
4 )

You can use show rules to customize the document style template before calling show-module() .
Setting any text and paragraph attributes works just out of the box. Furthermore, heading styles can be
set to affect the appearance of the module name (relative heading level 1), function or variable names
(relative heading level 2) and the word Parameters (relative heading level 3), all relative to what is
set with the parameter first-heading-level of show-module() .
Finally, if that is not enough, you can design a completely new style template. Examples thereof can
be found in the folder src/styles/ in the GitHub Repository.

V.a Customizing Colors (mainly for the default style)

The colors used by a style (especially the color in which types are shown) can be set through the option
colors of show-module() . It expects a dictionary with colors as values. Possible keys are all type
names as well as signature-func-name which sets the color of the function name as shown in a
function signature.
The default theme defines a color scheme colors-dark along with the default colors which
adjusts the plain colors for better readability on a dark background.

1 #tidy.show-module( typ
2 docs,
3 colors: tidy.styles.default.colors-dark
4 )

With a dark background and light text, these colors produce much better contrast than the default
colors:

space
Produces space.
Parameters
space(amount: length )

9
V.b Predefined styles
Currently, the two predefined styles tidy.styles.default and tidy-styles.minimal are available.
• tidy.styles.default : Loosely imitates the online documentation of Typst functions.
• tidy.styles.minimal : A very light and space-efficient theme that is oriented around
simplicity. With this theme, the example from above looks like the following:

wiggly
draw-sine(width: length , height: length , periods: int float ) -> content

Draw a sine function with 𝑛 periods into a rectangle of given size.

Example:

#draw-sine(1cm, 0.5cm, 2)

Parameters:
width ( length ) – Height of bounding rectangle.
height ( length ) – Width of bounding rectangle.
periods ( int or float ) – Number of periods to draw.
Example with many periods:

#draw-sine(4cm, 1.3cm, 10)

10
VI Help command
This feature is still experimental and may change a bit in its details. Output customization will be made
available with the introduction of user-defined types into Typst. The search feature will then move
into a nested function, i.e., help.search() .
With tidy, you can easily add a help command to your package. This allows the users of your package
to call #your-package.help("foo") to get the docs for the specified definition printed right in their
document. This makes reading up on options and discovering features in your package effortless. After
the desired information has been gathered, it’s no more than deleting a line of document source code
to make the docs vanish into the hidden realms of repositories once again!
As a demonstration, calling #tidy.help("parse-module") produces the following (clipped) output
into the document.

? help ?
parse-module(
content: str ,
name: str ,
label-prefix: auto str ,
require-all-parameters: bool ,
scope: dictionary ,
preamble: str ,
enable-curried-functions: bool ,
old-syntax: bool
)

Parse the doc-comments of a typst module. This function returns a dictionary with the keys
• name : The module name as a string.
•• default
functions
types
label-prefix
description
args : A: list
:The
(optional):
:A The
(optional):
dictionary Aoffunction’s
function
prefix
list
Default
of info for documentations
internal
of accepted
value
objects for labels
argument
this
description.
for each as dictionaries.
and
argument.
functionreferences.
types. argument.
Parameters:
The label
These
See again
prefix
are will
dictionaries
for
automatically
outputting
with the
the
be keys
the
results
nameof of
thisthe
function.
module if not given explicity.
This feature supports:
show-module

The
content ( strdocumentation
• function ) – Content
description of dictionaries
(optional): file tocontain
analyze
The description
.typ forfor
the
the docstrings.
argument.
keys
• name
function
• ( name
and
str =: The
variable
"" ) –function
The name
definitions,
for the module.
name.
• label-prefix
definitions( defined in nested submodules, e.g.,
auto or str = auto ) – The label-prefix for internal function references. If auto , the label-prefix name
#your-package.help("sub.bar.foo")
will be the module name.
• require-all-parameters
asking only for the(parameter
bool = false )description ofparameters
– Require that all a function, e.g., are documented and fail if some
of a functions
are not.
#your-package.help("foo(param1)")
• scope
lazy (evaluation
dictionary =of (:)doc-comment
) – A dictionary of processing
definitions that (even
are thenloading
available intidy is made
all function lazy).
and parameter
descriptions.
Don’t pay for what you don’t use!
preamble ( str = "" ) – Code to prepend to all code snippets shown with #example() . This can for instance be used to
• search through the entire package documentation, e.g.,
import something from the scope.
#your-package.help(search: "module")
enable-curried-functions ( bool = true ) – Whether to enable the detection of curried functions.

VI.a Setup
old-syntax ( bool = false ) – Whether to use the old documentation syntax.

If you have already documented your code, adding such a help function will require only little further
effort in implementation. In your root library file, add some code of the following kind:

1 #let help(..args) = { typ

2 import "@preview/tidy:0.4.3"
3 let namespace = (
4 ".": read.with("/src/my-package.typ")
5 )
6 tidy.generate-help(namespace: namespace, package-name: "tidy")(..args)
7 }

11
First, we set up a namespace dictionary that reflects the way that definitions can be accessed by a
user. Note that due to import statements that import from a file, this may not reflect the actual file
structure of your repository. Take care to provide read.with() objects with the filename prepended
instead of directly calling read() . This allows tidy to only lazily read the source files upon a help
request from the end user.
As a more elaborate example, let us look at some library root file for a maths package called heymath .

heymath.typ
1 #import "vec.typ": vec-add, vec-subtract // import definitions into root typ
2 #import "matrix.typ" // submodule "matrix"
3
4 /// ...
5 #let pi-squared = 9.86960440108935861883

Our namespace dictionary could then look like this:

1 let namespace = ( typc

2 ".": (read.with("/heymath.typ"), read.with("/vec.typ"))
3 "matrix": read.with("/matrix.typ")
4 "matrix.solve": read.with("/solve.typ")
5 )

Since the symbols from vec.typ are imported directly into the library (and are accessible through
heymath.vec-add() and heymath.vec-subtract() ), we add this file to the root together with the
main library file. Both files will be internally concatenated for doc-comment processing. The content
of matrix.typ , however, can only be accessed through heymath.matrix. (by the user) and so we
place matrix.typ at the key matrix . For nested submodules, write out the complete name “path”
for the key. As an example, we have added matrix.solve – a module that would be imported
within matrix.typ – to the code sample above. It is advised not to change the signature of the
help function manually in order to keep consistency between different packages using this
features.

VI.b Searching
It is also possible to search the package documentation via the search argument of the help function:
#tidy.help(search: "module") . This feature is even more experimental.

? help ?
• parse-module()
• show-module()

parse-module(
content: str ,
name: str ,
label-prefix: auto str ,
require-all-parameters: bool ,
scope: dictionary ,
preamble: str ,
enable-curried-functions: bool ,
old-syntax: bool
)

Parse
• the doc-comments
:A
description
args
types
default
functions dictionary
label-prefix : A: list
:The
(optional):
(optional):
Theof afunction
typst
offunction’s
A of
listinfo
Default
prefix module.
objects This
description.
of accepted
value
for for
for
documentations
internal each
argument
this function
labelsfunction
argument. returns
types.
and a dictionary with the keys
argument.
as dictionaries.
references.
Parameters:
The label
These
See again
prefix
are will
show-module dictionaries
for
automatically
outputting
with the
the
be keys
the
results
name of of
thisthefunction.
module if not given explicity.
• name : The module name as a string.
( str
The• function
content
module-doc ( documentation
) – Content )of– dictionaries
(optional):
dictionary
description Module file
documentation
tocontain
analyze
The description
.typ for
thefor
theinformation
docstrings.
argument. as returned by parse-module .
keys
• ( (name
name
style str =: The
module "" )or–function
The name for= the
name.
dictionary module. )
– The output style to use. This can be a module defining the
styles.default
functions show-outline , show-type , show-function12 , show-parameter-list and show-parameter-block or a
label-prefix ( auto or str = auto ) – The label-prefix for internal function references. If auto , the label-prefix name
dictionary with functions for the same keys.
will be the module name.
first-heading-level ( int = 2 ) – Level for the module heading. Function names are created as second-level headings
require-all-parameters ( bool = false ) – Require that all parameters of a functions are documented and fail if some
and the “Parameters” heading is two levels below the first heading level.
are not.
VI.c Output customization (for end-users)
The default style for help output should work more or less for light and dark documents but is
otherwise not very customizable. This is intended to be changed when user-defined types are available
in Typst because these would provide the ideal interface for such customization. Until then, I do not
deem it much sense to provide a temporary solution that need.

VI.d Notes about optimization (for package developers)

When set up in the form as shown above, the package tidy is only imported when a user calls
help for the first time and not at all if the feature is not used (don’t pay for what you don’t use). The
files themselves are also only read when a definition from a specific submodule in the “namespace” is
requested. In the case of extremely long code files, it could make sense to separate the documentation
from the implementation by adding “documentation files” that only contain a declaration plus doc-
comment for each definition – with the body left empty.

1 #let my-really-long-algorithm( typ

2 /// The inputs for the algorithm. -> array
3 inputs,
4 /// Some parameters. -> none | dictionary
5 parameters: none
6 ) = { }

The advantage is that the source code is not as crowded with (sometimes very long) doc-comments
and that doc-comment parsing may get faster. On the downside, there is an increased maintenance
overhead due to the need of synchronizing the actual file and the documentation file (especially when
the interface of a function changes).

13
VII Doc-comment testing
Tidy supports small-scale doc-comment tests that are executed automatically and throw appropriate
error messages when a test fails.
In every doc-comment, the function test(..tests, scope: (:)) is available. An arbitrary number
of tests can be passed in and the evaluation scope may be extended through the scope parameter.
Any definition exposed to the doc-comment evaluation context through the scope parameter passed
to parse-module() (see Section III) is also accessible in the tests. Let us create a module num.typ
with the following content:

1 /// #test( typ

2 /// `num.my-square(2) == 4`,
3 /// `num.my-square(4) == 16`,
4 /// )
5 #let my-square(n) = n * n

Parsing and showing the module will run the doc-comment tests.

1 #import "num.typ" typ

2 #let module = tidy.parse-module(
3 read("num.typ"),
4 name: "num",
5 scope: (num: num)
6 )
7 #tidy.show-module(module) // tests are run here

A few test assertion functions are available to improve readability, simplicity and error mes-
sages. Currently, these are eq(a, b) for equality tests, ne(a, b) for inequality tests and
approx(a, b, eps: 1e-10) for floating point comparisons. These assertion helper functions are
always available within doc-comment tests.
Doc-comment tests can be disabled by passing enable-tests: false to show-module() .

14
VIII Function documentation
Let us now self-document this package:

tidy
• parse-module()
• show-module()
• generate-help()
• default-layout-example()
• show-example()
• render-examples()

parse-module
Parse the doc-comments of a typst module. This function returns a dictionary with the keys
• name : The module name as a string.
• functions : A list of function documentations as dictionaries.
• label-prefix : The prefix for internal labels and references.
The label prefix will automatically be the name of the module if not given explicity.
The function documentation dictionaries contain the keys
• name : The function name.
• description : The function’s description.
• args : A dictionary of info objects for each function argument.
These again are dictionaries with the keys
• description (optional): The description for the argument.
• types (optional): A list of accepted argument types.
• default (optional): Default value for this argument.
See show-module() for outputting the results of this function.
Parameters
parse-module(
content: str ,
name: str ,
label-prefix: auto str ,
require-all-parameters: bool ,
scope: dictionary ,
preamble: str ,
enable-curried-functions: bool ,
old-syntax: bool
)

content str

Content of .typ file to analyze for docstrings.

name str

The name for the module.

Default: ""

label-prefix auto or str

The label-prefix for internal function references. If auto , the label-prefix name will be the module name.
Default: auto

15
 require-all-parameters bool

Require that all parameters of a functions are documented and fail if some are not.
Default: false

scope dictionary

A dictionary of definitions that are then available in all function and parameter descriptions.
Default: (:)

preamble str

Code to prepend to all code snippets shown with #example() . This can for instance be used to import something from
the scope.
Default: ""

enable-curried-functions bool

Whether to enable the detection of curried functions.

Default: true

old-syntax bool

Whether to use the old documentation syntax.

Default: false

show-module
Show given module in the given style. This displays all (documented) functions in the module.
Parameters
show-module(
module-doc: dictionary ,
style: module dictionary ,
first-heading-level: int ,
show-module-name: bool ,
break-param-descriptions: bool ,
omit-empty-param-descriptions: bool ,
omit-private-definitions: bool ,
omit-private-parameters: bool ,
show-outline: bool ,
sort-functions: auto none function ,
enable-tests: bool ,
enable-cross-references: bool ,
colors: auto dictionary ,
local-names: dictionary
) -> content

module-doc dictionary

Module documentation information as returned by parse-module().

16
style module or dictionary

The output style to use. This can be a module defining the functions show-outline , show-type , show-function ,
show-parameter-list and show-parameter-block or a dictionary with functions for the same keys.

Default: styles.default

first-heading-level int

Level for the module heading. Function names are created as second-level headings and the “Parameters” heading is
two levels below the first heading level.
Default: 2

show-module-name bool

Whether to output the name of the module at the top.

Default: true

break-param-descriptions bool

Whether to allow breaking of parameter description blocks.

Default: false

omit-empty-param-descriptions bool

Whether to omit description blocks for parameters with empty description.

Default: true

omit-private-definitions bool

Whether to omit functions and variables starting with an underscore.

Default: false

omit-private-parameters bool

Whether to omit named function arguments starting with an underscore.

Default: false

show-outline bool

Whether to output an outline of all functions in the module at the beginning.

Default: true

sort-functions auto or none or function

Function to use to sort the function documentations. With auto , they are sorted alphabetically by name and with
none they are not sorted. Otherwise a function can be passed that each function documentation object is passed to
and that should return some key to sort the functions by.
Default: auto

17
 enable-tests bool

Whether to run doc-comment tests.

Default: true

enable-cross-references bool

Whether to enable links for cross-references. If set to auto, the style will select its default color set.
Default: true

colors auto or dictionary

Give a dictionary for type and colors and other colors.

Default: auto

local-names dictionary

Language-specific names for strings used in the output. Currently, these are parameters and default . You can
for example use: local-names: (parameters: [Parameter], default: [Standard], variables: [Variablen]) .
If set to auto , automatic translations will be used according to the current document language.
Default: auto

generate-help
Generates a help function for your package that allows the user to prints references directly into their document while
typing. This allows them to easily check the usage and documentation of a function or variable.
Parameters
generate-help(
namespace: dictionary ,
package-name: str ,
style: dictionary ,
onerror: function ,
old-syntax: bool
)

18
 namespace dictionary

This dictionary should reflect the “namespace” of the package in a flat dictionary and contain read.with()
instances for the respective code files. Imagine importing everything from a package, #import "mypack.typ": * .
How a symbol is accessible now determines how the dictionary should be built. We start with a root key,
(".": read.with("lib.typ")) . If lib.typ imports symbols from other files into its scope, these files should be
added to the root along with lib.typ by passing an array:

1 ( typ
2 ".": (read.with("lib.typ"), read.with("more.typ")),
3 "testing": read.with("testing.typ")
4 )

Here, we already show another case: let testing.typ be imported in lib.typ but without * , so that the symbols
are accessed via testing. . We therefore add these under a new key. Nested files should be added with multiple dots,
e.g., "testing.float." .
By providing instances of read() with the filename prepended, you allow tidy to read the files that are not part of the
tidy package but at the same time enable lazy evaluation of the files, i.e., a file is only opened when a definition from
this file is requested through help() .
Default: (".": () => "")

package-name str

The name of the package. This is required to give helpful error messages when a symbol cannot be found.
Default: ""

style dictionary

A tidy style that is used for showing parts of the documentation in the help box. It is recommended to leave this at the
help style which is particularly designed for this purpose. Please post an issue if you have problems or suggestions
regarding this style.
Default: styles.help

onerror function

What to do with errors. By default, an assertion is failed (the document panics).

Default: msg => assert(false, message: msg)

old-syntax bool

Whether to use the old parser.

Default: false

default-layout-example
Default example layouter used with show-example().

19
Parameters
default-layout-example(
code: raw ,
preview: content ,
dir: direction ,
ratio: int ,
scale-preview: auto ratio ,
code-block: function ,
preview-block: function ,
col-spacing: length
)

code raw

Code raw element to display.

preview content

Rendered preview.

dir direction

Direction for laying out the code and preview boxes.

Default: ltr

ratio int

Configures the ratio of the widths of the code and preview boxes.
Default: 1

scale-preview auto or ratio

How much to rescale the preview. If set to auto, the the preview is scaled to fit the box.
Default: auto

code-block function

The code is passed to this function. Use this to customize how the code is shown.
Default: block

preview-block function

The preview is passed to this function. Use this to customize how the preview is shown.
Default: block

col-spacing length

Spacing between the code and preview boxes.

Default: 5pt

20
 show-example
Takes a raw elements and both displays the code and previews the result of its evaluation.
The code is by default shown in the language mode lang: typc (typst code) if no language has been specified. Code in
typst markup lanugage ( lang: typ ) is automatically evaluated in markup mode.
Lines in the raw code that start with >>> are removed from the outputted code but evaluated in the preview.
Lines starting with <<< are displayed in the preview, but not evaluated.
Parameters
show-example(
code: raw ,
scope: dictionary ,
preamble: str ,
mode: auto str ,
inherited-scope: dictionary ,
layout: function ,
..options: any
)

code raw

Raw object holding the example code.

scope dictionary

Additional definitions to make available in the evaluation of the preview.

Default: (:)

preamble str

Code to prepend to the snippet. This can for example be used to configure imports. This is currently only supported in
markup mode, see show-example.mode.

Default: ""

mode auto or str

Language mode. Can be auto , "markup" , or "code" .

Default: auto

inherited-scope dictionary

This parameter is only used internally. Definitions that are made available to the entire parsed module.
Default: (:)

layout function

Layout function which is passed to code, the preview and all other options, see show-example.options.
Default: default-layout-example

..options any

Additional options to pass to the layout function.

21
 render-examples
Adds the two languages example and examplec to raw that can be used to render code examples side-by-side with an
automatic preview.
This function is intended to be used in a show rule

1 #show: render-example typ

Parameters
render-examples(
body: any ,
scope: dictionary ,
layout: function
)

body any

Body to apply the show rule to.

scope dictionary

Scope
Default: (:)

layout function

Layout function which is passed the code, the preview and all other options, see show-example.options.
Default: default-layout-example

22