typst-count

A command-line tool to count words and characters in Typst documents.

Features

Count words and characters from compiled Typst documents
Counts only rendered text (excludes markup, code, and comments)
Handles imported and included files automatically
Multiple output formats: human-readable, JSON, CSV
Support for multiple input files with totals
CI-friendly with limit checks and proper exit codes
Flexible display modes for different use cases

Installation

From crates.io

cargo install typst-count

From source

git clone https://github.com/HollowNumber/typst-count.git
cd typst-count
cargo install --path .

Usage

Basic Usage

# Count both words and characters
typst-count document.typ

# Count only words
typst-count document.typ --words

# Count only characters
typst-count document.typ --characters

Output Formats

# Human-readable output (default)
typst-count document.typ

# JSON output for scripting
typst-count document.typ --format json

# CSV output for data analysis
typst-count document.typ --format csv

Multiple Files

# Count multiple files with totals
typst-count doc1.typ doc2.typ doc3.typ

# Output results to a file
typst-count *.typ --output results.json --format json

Advanced Options

# Exclude imported/included files (count only main file)
typst-count document.typ --exclude-imports

# Quiet mode (exit code only, useful in CI)
typst-count document.typ --quiet

# Set limits with exit codes (useful for CI/CD)
typst-count document.typ --min-words 500 --max-words 1000
typst-count document.typ --min-chars 2000 --max-chars 5000

How It Works

typst-count compiles your Typst document and extracts the rendered text content. This means:

Counted: All text that appears in the final rendered document
Counted: Content from imported/included files (by default)
Counted: Markup syntax (like *bold*, _italic_)
Not counted: Code blocks and inline code
Not counted: Comments
Not counted: Function definitions and calls

Counting Method

Words: Split by whitespace (same as wc -w). Note: For languages without spaces (e.g., Chinese, Japanese), each character may be counted as a separate "word"
Characters: Total character count including spaces and punctuation

Examples

Example Output (Human-readable)

File: document.typ
Characters: 1,842
Words: 287

Example Output (JSON)

{
  "files": [
    {
      "path": "document.typ",
      "characters": 1842,
      "words": 287
    }
  ],
  "total": {
    "characters": 1842,
    "words": 287
  }
}

CI/CD Integration

Check word count limits in your CI pipeline:

# .github/workflows/check-docs.yml
- name: Check documentation word count
  run: |
    cargo install typst-count
    typst-count docs.typ --min-words 1000 --max-words 5000

Exit codes:

0: Success (within limits if specified)
1: Below minimum or above maximum limit
2: Compilation or other error

Comparison with Other Tools

vs wc: Counts only rendered text, not markup/code
vs Typst word count function: Can be used in CI/CD and with multiple files
vs Tinymist LSP: Standalone tool, doesn't require editor integration

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development

# Clone the repository
git clone https://github.com/HollowNumber/typst-count.git
cd typst-count

# Run tests
cargo test

# Run clippy
cargo clippy --all-targets

# Format code
cargo fmt

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built with Typst - A new markup-based typesetting system
Inspired by classic tools like wc and modern Typst tooling

Related Projects

Typst - The Typst compiler
Tinymist - Typst LSP server with editor integration

typst-count 0.1.0