Documentation

Edit and preview this documentation, which is built with fugo from the docs directory of the repository.

This site is built with fugo from the docs/ directory of the repository, with its own theme (Tera templates, Sass and a small script).

Preview#

cargo build --release -p ssg-cli
target/release/fugo server -s docs

Open http://localhost:1313/. Pages reload as you save.

Where things are#

text
docs/
├── config.toml
├── content/            the pages, one Markdown file each
├── data/               generated reference data (do not edit by hand)
├── layouts/            the theme's templates, shortcodes and render hooks
└── assets/             Sass and JavaScript

The function, object and command references are generated by content adapters from docs/data/, which the tests write from the code:

File	Written from	Regenerate
`template_api.json`	`crates/funcs/src/spec.rs`	`INSTA_UPDATE=always cargo test -p ssg-testkit contract`
`commands.json`	the command line definition	`INSTA_UPDATE=always cargo test -p ssg-cli docs_data`
`objects.toml`	written by hand, checked against the code	`cargo test -p ssg-view docs_objects`

To change a function’s description, change spec.rs, not the JSON.

Writing#

Write for someone building a site: what it does, a working example, then the details.
Show TOML, YAML and JSON configuration with the code-toggle shortcode.
Link to pages by their path (/templates/lookup-order/); a link to a page that does not exist is a build warning, and the docs test fails on warnings.
Check that examples work: build a small site with them.

The docs test (cargo test -p ssg-cli docs_site) builds the site and fails on any warning or template error.