# 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:
- Typst files are compiled by calling your local Typst CLI; we expect one to be installed.
- Files matching those in the `passthrough_copy` array in `compile-typst-site.toml` are copied over. Matching can use globs, processed with the `globset` crate. This is probably unidiomatic to file paths (`*` matches recursively instead of just the first layer).
- 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:
```rust
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
```text
compile-typst-site v1.0.0
Binary tool 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.
```