Typsite Documentation

Typsite is a tool for building static websites. It uses pure Typst to write content and processes it through Typsite to generate a fully functional static site.

• Standard Typst expressions
• Framework support: hierarchical headings, section templates, sidebar, footer
• Rich text: paragraphs, sections, quotes, code blocks, math formulas, footnotes, page embedding
• Supports modern web standards such as HTML5, CSS3, and JavaScript (ES6+)
• Incremental compilation and real-time preview

Typst is a modern typesetting system, similar to LaTeX, but designed to be more concise and easier to learn. It is primarily used to create beautifully typeset documents such as academic papers, books, and reports.

You can find the official English documentation here: Typst Document
For a Chinese tutorial on Typst, I highly recommend: The Typst Blue Book
(Oh my, the author is clearly aware that they're explaining an ontology!).

The rest of this section will introduce Typst & HTML → Typsite

• Download the binary from the release

  • Make sure you have Typst 0.13+ installed

• Build via Nix & Flakes

  • Ensure you’ve enabled experimental-features = nix-command flakes experimental-features = nix-command flakes

git clone https://github.com/Glomzzz/typsite.git

cd typsite
nix build .

git clone https://github.com/Glomzzz/typsite.git

cd typsite
nix build .

Run typsite init typsite init to initialize a Typsite project in the current directory.

.
├── root         ---  Typst root directory
│   ├── index.typ    --- Main article
│   └── lib.typ      --- Typsite library file
├── .typsite     ---  Typsite configuration directory
│   ├── assets       ---  Resources (synced to output directory)
│   ├── components   ---  Component templates
│   ├── themes       ---  Code highlighting themes
│   ├── rewrite      ---  Rewrite templates
│   ├── schemas      ---  Page templates
│   └── options.toml ---  Project configuration
├── .cache       ---  Cache directory
└── publish      ---  Output directory

.
├── root         ---  Typst root directory
│   ├── index.typ    --- Main article
│   └── lib.typ      --- Typsite library file
├── .typsite     ---  Typsite configuration directory
│   ├── assets       ---  Resources (synced to output directory)
│   ├── components   ---  Component templates
│   ├── themes       ---  Code highlighting themes
│   ├── rewrite      ---  Rewrite templates
│   ├── schemas      ---  Page templates
│   └── options.toml ---  Project configuration
├── .cache       ---  Cache directory
└── publish      ---  Output directory

Typsite is compatible with most native Typst syntax:

Usage: typsite <COMMAND>

Commands:
  init     Initialize a new Typsite project in the specified directory
  compile  Compile or watch a project; specify input/output [alias: c]
  clean    Clear cache and output directories
  help     Print this message or help info for a subcommand

Options:
  -h, --help     Print help
  -V, --version  Print version info

Usage: typsite <COMMAND>

Commands:
  init     Initialize a new Typsite project in the specified directory
  compile  Compile or watch a project; specify input/output [alias: c]
  clean    Clear cache and output directories
  help     Print this message or help info for a subcommand

Options:
  -h, --help     Print help
  -V, --version  Print version info

Initialize a new Typsite project in the specified directory

Usage: typsite init [OPTIONS]

Options:
  -d, --dir <DIR>  Project root directory [default: ./]
  -h, --help       Print help

Initialize a new Typsite project in the specified directory

Usage: typsite init [OPTIONS]

Options:
  -d, --dir <DIR>  Project root directory [default: ./]
  -h, --help       Print help

Compile or watch the project, specifying input/output directories

Usage: typsite compile [OPTIONS]

Options:
      --port <PORT>      Server port [default: 0]
      --config <CONFIG>  Config path [default: ./.typsite]
      --cache <CACHE>    Cache directory [default: ./.cache]
  -i, --input <INPUT>    Typst root directory [default: ./root] [alias: --i]
  -o, --output <OUTPUT>  Output directory [default: ./publish] [alias: --o]
      --no-pretty-url
      --no-short-slug
  -h, --help             Print help

Compile or watch the project, specifying input/output directories

Usage: typsite compile [OPTIONS]

Options:
      --port <PORT>      Server port [default: 0]
      --config <CONFIG>  Config path [default: ./.typsite]
      --cache <CACHE>    Cache directory [default: ./.cache]
  -i, --input <INPUT>    Typst root directory [default: ./root] [alias: --i]
  -o, --output <OUTPUT>  Output directory [default: ./publish] [alias: --o]
      --no-pretty-url
      --no-short-slug
  -h, --help             Print help

Clear cache and output directories

Usage: typsite clean [OPTIONS]

Options:
  -o, --output <OUTPUT>  Output directory [default: ./publish]
  -c, --cache <CACHE>    Cache directory for typst_html_export content [default: ./.cache]
  -h, --help             Print help

Clear cache and output directories

Usage: typsite clean [OPTIONS]

Options:
  -o, --output <OUTPUT>  Output directory [default: ./publish]
  -c, --cache <CACHE>    Cache directory for typst_html_export content [default: ./.cache]
  -h, --help             Print help

View the list of syntax highlighting and supported languages  
Usage: typsite syntect [OPTIONS]

Options:
      --config <CONFIG>  Config path [default: ./.typsite]
  -h, --help             Print help

View the list of syntax highlighting and supported languages  
Usage: typsite syntect [OPTIONS]

Options:
      --config <CONFIG>  Config path [default: ./.typsite]
  -h, --help             Print help

You can view all default configurations here:

Based on these, you can fully customize your entire site.

• schema: Page templates, handling page structure
• components / rewrites: Components/Rewriters, build up the page content
• assets: Resource files, automatically synced during compilation
• themes: Code highlighting files
• syntaxes: Code syntaxes files