fy-docs

English | 简体中文

A Cargo subcommand for building and previewing Typst specification documents. Run it inside a project containing docs/main.typ to generate a local reading page, watch source changes, and produce a versioned PDF when needed.

Installation

Via Cargo (Recommended for Rust developers)

cargo install fy-docs

The installed executable is cargo-fy-docs, which Cargo discovers as the cargo fy-docs command.

Pre-built Binaries (Direct Download)

Pre-compiled binaries for Windows (x64 / ARM64), macOS (Apple Silicon / Intel), Linux (x64 / ARM64, musl static), and FreeBSD (x64) are available on the GitHub Releases page. Download the archive for your platform, extract cargo-fy-docs into a directory on your PATH, and run:

cargo-fy-docs --version

Usage

# Scaffold a docs/ directory with a starter main.typ, embedded fy-spec template, and modules/ folder.
cargo fy-docs init

# Full build: compile all language HTML pages and PDF 2.0 specifications (default command, CI-safe).
cargo fy-docs
# or explicitly:
cargo fy-docs build

# Build offline HTML documentation only.
cargo fy-docs html

# Build versioned PDF 2.0 specification(s) only.
cargo fy-docs pdf

# Interactive development: start local dev server with live reload and browser preview.
cargo fy-docs dev

Common options:

cargo fy-docs --lang zh-CN    # Target a specific language
cargo fy-docs --open          # Open in browser after build
cargo fy-docs --root D:\Code  # Explicitly specify Typst root
cargo fy-docs --with-pdf      # html/dev: also compile the print-edition PDF
cargo fy-docs dev --port 8181 # Customize dev server port
cargo fy-docs dev --no-open   # Dev mode without opening a browser

Output

The package name and version are read from [package] in Cargo.toml, including Cargo workspace inheritance. If the manifest has no package metadata, fy-docs falls back to the document's version: field and then to 0.1.0.

Document Layout

Single-language documentation layout:

project/
├── Cargo.toml
├── src/
└── docs/
    ├── main.typ             # Single Typst entry point
    ├── fy-spec/             # Embedded template library (lib.typ, self-contained)
    ├── modules/             # Specification source by module
    ├── target/              # Generated HTML reading pages (Git ignored)
    └── release/             # Versioned specification PDFs (Git ignored)

Multilingual (i18n) documentation layout:

project/
├── Cargo.toml
├── src/
└── docs/
    ├── fy-spec/             # Shared embedded template library (lib.typ)
    ├── zh-CN/               # Simplified Chinese specification
    │   ├── main.typ
    │   └── modules/
    ├── en/                  # English specification
    │   ├── main.typ
    │   └── modules/
    ├── target/              # Generated index.html, index_zh-CN.html, index_en.html
    └── release/             # Versioned PDFs for each language

docs/fy-spec/ contains the embedded styling templates (ISO B5 layout, semantic contract boxes, badges), ensuring specification documents are fully self-contained and reproducible without external dependencies.

docs/target/ and docs/release/ are generated artifacts and should be ignored by Git. They are intentionally separate from Cargo's target/release/ program artifacts.

Requirements

typst must be available on PATH (Typst 0.14 or later — the --pdf-standard 2.0 flag fy-docs passes requires it). fy-docs is developed and tested against Typst 0.15.

Changelog

Detailed release notes and migration guides for each version are documented in CHANGELOG.md.

License

Dual-licensed under MIT OR Apache-2.0, at your option.