Builders

typsphinx provides two builders for different use cases.

Overview

Builder

Output

Use Case

typst

.typ files

Edit Typst markup manually, use external Typst CLI

typstpdf

.pdf files

Direct PDF generation, CI/CD pipelines

typst Builder

The typst builder generates Typst markup files (.typ).

Usage

sphinx-build -b typst source/ build/typst

Output

  • Generates .typ files in the output directory

  • One file per document defined in typst_documents

  • Include files for multi-document projects

When to Use

  • You want to edit the generated Typst markup

  • You have a specific Typst CLI version

  • You need fine control over compilation

  • You want to learn Typst syntax

Manual Compilation

After generating .typ files, compile with Typst CLI:

# Install Typst CLI if needed
# https://github.com/typst/typst

# Compile to PDF
typst compile build/typst/index.typ output.pdf

typstpdf Builder

The typstpdf builder generates PDF files directly using typst-py.

Usage

sphinx-build -b typstpdf source/ build/pdf

Output

  • Generates .pdf files directly

  • No external tools required

  • Uses typst-py Python bindings

When to Use

  • You want PDF output immediately

  • You’re running in CI/CD without Typst CLI

  • You want self-contained builds

  • You don’t need to edit Typst markup

Advantages

  • No external dependencies: Everything runs in Python

  • Faster setup: No need to install Typst CLI

  • Reproducible builds: Same output across environments

  • CI/CD friendly: Works in restricted environments

Configuration

Both builders share the same configuration options in conf.py.

Document Definitions

typst_documents = [
    # (source, output, title, author, class)
    ("index", "main", "My Document", "Author", "typst"),
    ("api", "api-ref", "API Reference", "Author", "typst"),
]

Builder-Specific Options

There are no builder-specific options currently. All typst_* configuration options apply to both builders.

Choosing a Builder

Use typst if:

  • You want to customize the generated Typst code

  • You need specific Typst CLI features

  • You’re learning Typst and want to see the markup

Use typstpdf if:

  • You just want PDF output

  • You’re building in CI/CD

  • You want the simplest workflow

  • You don’t need to edit Typst code

Common Workflow

Development

During development, use typstpdf for quick feedback:

sphinx-build -b typstpdf source/ build/pdf
open build/pdf/index.pdf

Production

For production, you can use either builder:

# Option 1: Direct PDF (recommended)
sphinx-build -b typstpdf source/ build/pdf

# Option 2: Typst + manual compilation
sphinx-build -b typst source/ build/typst
typst compile build/typst/index.typ output.pdf

CI/CD

In CI/CD, typstpdf is recommended for simplicity:

- name: Build Documentation PDF
  run: |
    pip install typsphinx
    sphinx-build -b typstpdf docs/source docs/build/pdf

See Also