Typstyle Docs

Documentation Development

This section covers building and maintaining the typstyle documentation.

The documentation uses shiroa to build from Typst source files.

Building Documentation

❗ Important
Documentation build requires CLI help text and the typstyle plugin to be generated first. Use just build-docsjust build-docs to handle dependencies automatically, or run just generate-cli-helpjust generate-cli-help and just build-pluginjust build-plugin manually before building.

Development Server

Development server with auto-reload:

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

Static Build

Build static documentation:

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

Build Plugin

Build the typstyle plugin for embedded usage:

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

Generate CLI Help

Generate CLI help text:

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

This is used for cli-usage.

Documentation Structure

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
ℹ Note
The shiroa root directory is docs/pages/docs/pages/. For better organization, the main book configuration is located at docs/book.typdocs/book.typ and imported by docs/pages/book.typdocs/pages/book.typ.

Writing Documentation

Render Examples

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:

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

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_textwrap_text - Enable text wrapping
  • 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

Using Callout Components

The documentation supports various callout types for highlighting important information:

ℹ Note
This is a standard note callout for general information.
❗ Important
This is an important callout for critical information that users must be aware of.
⚠ Warning
This is a warning callout for potential issues or dangerous operations.
💡 Tip
This is a tip callout for helpful suggestions and best practices.
⚠ Caution
This is a caution callout for operations that require careful consideration.

You can also use custom titles:

❗ Custom Title
This callout has a custom title instead of the default "Important".

Documentation Workflow

  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