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 dev --port 8181 # Customize dev server port

Output

Artifact	Location
Offline HTML reading page	`docs/target/index.html`
Print-edition PDF	`docs/release/<package>_v<version>_specification.pdf`

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
    ├── fy-spec/             # Embedded specification template library (lib.typ, self-contained)
    ├── modules/             # Specification source, organized by module
    ├── target/              # Generated HTML, CSS, and JavaScript (Git ignored)
    └── release/             # Versioned specification PDFs (Git ignored)

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 with HTML export support (Typst 0.13 or later). 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.

fy-docs 0.1.6