Documentation Development

This section covers building and maintaining the Typstyle documentation.

The documentation uses shiroa to build from Typst source files.

Development server with auto-reload:

1
just dev-docs
2
# or manually:
3
shiroa serve docs/pages -w . --mode static-html

1
just dev-docs
2
# or manually:
3
shiroa serve docs/pages -w . --mode static-html

Build static documentation:

1
just build-docs
2
# or manually:
3
shiroa build docs/pages -w . --mode static-html

1
just build-docs
2
# or manually:
3
shiroa build docs/pages -w . --mode static-html

Build the typstyle plugin for embedded usage:

1
just build-plugin
2
# or manually:
3
cargo build -p typstyle-typlugin --release --target wasm32-unknown-unknown
4
cp target/wasm32-unknown-unknown/release/typstyle_typlugin.wasm contrib/typstyle-embedded/assets/typstyle.wasm

1
just build-plugin
2
# or manually:
3
cargo build -p typstyle-typlugin --release --target wasm32-unknown-unknown
4
cp target/wasm32-unknown-unknown/release/typstyle_typlugin.wasm contrib/typstyle-embedded/assets/typstyle.wasm

Generate CLI help text:

1
just generate-cli-help
2
# or manually:
3
cargo run -p typstyle -- --help > docs/assets/generated/cli-help.txt

1
just generate-cli-help
2
# or manually:
3
cargo run -p typstyle -- --help > docs/assets/generated/cli-help.txt

This is used for cli-usage.

The documentation is organized as follows:

• docs/book.typdocs/book.typ — main book configuration and metadata
• docs/pages/docs/pages/ — individual documentation pages
• docs/packages/docs/packages/ — dependent third party packages not in universe
• docs/templates/docs/templates/ — page templates and components
• docs/assets/docs/assets/ — static assets and generated content

To show before/after formatting examples automatically, use the render-examplesrender-examples feature:

1. Enable automatic rendering by adding #show: render-examples#show: render-examples to your document
2. Write code examples using ```typst ``````typst ``` code blocks - they will automatically show before/after formatting. You can set the langlang parameter of render-examplesrender-examples to set which raw code language to render as examples (default: "typst""typst")

3. Configure formatting using special comments in your examples:

   1
   ```typst
   2
   /// typstyle: wrap_mode=fill, max_width=40
   3
   这是一个中文段落，包含链接 https://typst.app/ 和*强调文本*。
   4
   続いて`コード要素`と https://docs.typst.app/ を含む日本語の段落です。
   5
   ```

   1
   ```typst
   2
   /// typstyle: wrap_mode=fill, max_width=40
   3
   这是一个中文段落，包含链接 https://typst.app/ 和*强调文本*。
   4
   続いて`コード要素`と https://docs.typst.app/ を含む日本語の段落です。
   5
   ```

Configuration options supported in the comment are those available in the embedded typstyle package:

• max_width=Nmax_width=N - Set line width for this example
• wrap_mode=fillwrap_mode=fill - Wrap text to the configured width
• wrap_mode=sentencewrap_mode=sentence - Place each sentence on its own line
• wrap_mode=fill-sentencewrap_mode=fill-sentence - Place each sentence on its own line and wrap long sentences
• See the embedded typstyle documentation for all available options

The system automatically:

• Parses configuration from /// typstyle:/// typstyle: comments
• Formats the code with typstyle using the specified config
• Displays side-by-side before/after comparison
• Shows the active configuration options

The documentation supports various callout types for highlighting important information:

You can also use custom titles:

1. Write content in Typst format
2. Test locally with just dev-docsjust dev-docs
3. Build static version with just build-docsjust build-docs
4. For GitHub Pages deployment, use just build-docs-ghjust build-docs-gh (sets --path-to-root /typstyle/--path-to-root /typstyle/ for proper asset paths)
5. Review generated HTML output