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

cargo install fy-docs

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

Usage

# Scaffold a docs/ directory with a starter main.typ and bundled template.
cargo fy-docs init

# Interactive preview: build HTML, open the browser, and watch .typ files.
cargo fy-docs

# Build the offline HTML reading page only.
cargo fy-docs build

# Build the HTML page and a print-edition PDF together.
cargo fy-docs build --with-pdf

# Build only the print-edition PDF.
cargo fy-docs pdf

Common options:

cargo fy-docs --root D:\Code\fy
cargo fy-docs --port 8181
cargo fy-docs --no-open

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

project/
├── Cargo.toml
├── src/
├── target/                  # Program build artifacts
└── docs/
    ├── main.typ             # Typst entry point
    ├── modules/             # Specification source, organized by module
    ├── target/              # Generated HTML, CSS, and JavaScript
    └── release/             # Versioned specification PDFs

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 with HTML export support (Typst 0.13 or later). fy-docs is developed and tested against Typst 0.15.

License

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