Reference¶

Nitty-gritty technical descriptions of how compile-typst-site works. Most useful when you need detailed information about usage, requirements, and inner workings.

Concepts¶

compile-typst-site expects to be called somewhere under the following directory structure:

.
├── src/
├── templates/
└── compile-typst-site.toml

That is, just like cargo, just, uv, and so on, you can use compile-typst-site while in a subdirectory of the project root.

The directory . (one that contains a compile-typst-site.toml file) is known as the “project root.”

When you do so, it looks at every file in src. For each such file, one of the following happens, checked in the following order:

Files matching those in the passthrough_copy array in compile-typst-site.toml are copied over. Matching can use globs. Files are rooted in the content src directory, not the project root.
Typst files are compiled by calling your local Typst CLI; we expect one to be installed.
Other files are ignored.

If file watching is turned on, changes in src will only recompile that file. Changes in templates will recompile the entire project (all of src). We aren’t smart enough to detect exactly which dependents to recompile.

Config File API¶

The configuration file at compile-typst-site.toml is specified as such:

struct ConfigFile {
    /// Array of globs to match for passthrough-copying.
    ///
    /// Example in the TOML config file: `passthrough_copy = ["*.css", "*.js", "assets/*"]
    passthrough_copy: Option<Vec<String>>,
    /// Command to run before a full rebuild.
    ///
    /// Strings should not contain $ unless the symbol begins:
    /// - $PROJECT_ROOT, which is replaced with the path to the project root.
    ///
    /// E.g., `passthrough_copy = ["python", "$PROJECT_ROOT/prebuild.py"]`.
    init: Option<Vec<String>>,
    /// Command to run to post-process HTML files generated by Typst.
    ///
    /// Must take in stdin and return via stdout.
    ///
    /// Strings should not contain $ unless the symbol begins:
    /// - $PROJECT_ROOT, which is replaced with the path to the project root.
    ///
    /// Example in the TOML config file: `post_processing_typ = ["python", "$PROJECT_ROOT/post_processing_script.py"]`.
    post_processing_typ: Option<Vec<String>>,
    /// Convert paths literally instead of magically tranforming to index.html.
    ///
    /// i.e., ./content.typ goes to ./content.html instead of defaulting to ./content/index.html.
    ///
    /// Example in the TOML config file: `literal_paths = true`
    literal_paths: Option<bool>,
    /// Typst cannot yet glob-find multiple files, which is a problem if one wants to list, e.g., all blog posts on a page.
    /// To work around this, we write all Typst files(?) as a JSON to the project root directory.
    ///
    /// We also let you query for data. (You might want the dates of those blog posts to appear on your listing page).
    /// This is slower than the other options because we have to call `typst query`.
    ///
    /// Must be one of "disabled", "enabled", "include-data"
    ///
    /// Example in the TOML config file: `file_listing = "enabled"`
    file_listing: Option<String>,
}

CLI API¶

compile-typst-site v2.0.2
Command-line program for static site generation using Typst.

Usage:
  compile-typst-site [flags] [options]

Flags:
  -h --help            Show this help message.
  -V --version         Show the application version.
  -w --watch           Build and then watch for changes.
  -s --serve           Build and then watch for changes while serving website locally.
  -i --ignore-initial  Ignore initial full-site compilation step.
  -v --verbose         Enable verbose logging.
  -t --trace           Enable very verbose logging.

Options:
  -p --path STRING  Use the specified path as the project root.