Building from source¶
You need a stable Rust toolchain, git, Python 3.12+ (for the Python package) and Node 22+ (for the VS Code extension and screenshots).
git clone https://github.com/buchochelliq-labs/verlato-core
cd verlato-core
The native executable¶
cargo build --release -p verlato
scripts/fetch_intentumdiff_parsers.sh # parser bundle -> target/release/wasm
target/release/verlato doctor engine
fetch_intentumdiff_parsers.sh [DEST] downloads the pinned, checksum-verified IntentumDiff
parser bundle (by default next to the release binary, where Verlato finds it). The engine
itself is a git dependency on
intentumdiff-core, fetched by
Cargo. To build without the engine (git evidence only), use --no-default-features.
A release-style bundle (executable, wasm/, licence and README in one archive) is made by
scripts/package_native_bundle.sh and checked by scripts/test_native_bundle.sh; see
Releasing.
The Python package¶
The package is built with maturin from crates/verlato-python (the
verlato._native extension) and python/verlato:
python -m venv .venv && . .venv/bin/activate
scripts/fetch_intentumdiff_parsers.sh python/verlato/wasm # the bundle the wheel ships
python -m pip install -e '.[dev]' # builds the extension
verlato --version
After changing Rust code, rebuild with maturin develop --release (or reinstall). A wheel:
maturin build --release.
The VS Code extension¶
cd vscode-extension
npm ci
npm run build # TypeScript -> dist/
npx @vscode/vsce package # verlato-vscode-<version>.vsix (compiles first via vscode:prepublish)
The release builds it with scripts/package_extension.sh (npm ci, npm test, then
vsce package --pre-release while Verlato is a pre-release); run it the same way to reproduce the published
file:
scripts/package_extension.sh # writes dist/verlato-vscode-<version>.vsix
code --install-extension dist/verlato-vscode-*.vsix --force
For development, open the repository in VS Code and press F5: .vscode/launch.json
starts an Extension Development Host with the extension loaded. To use your build of the
native executable, the extension finds target/release/verlato next to vscode-extension/
automatically, or set verlato.cliPath.
On Windows, scripts\install_vscode_extension.cmd does all of it: installs the package into
the repository's .venv, builds and packages the extension, installs it, and writes
verlato.cliPath (options -SkipPythonInstall, -SkipNpmInstall, -SkipPackage,
-SkipConfigureCliPath, -PreRelease).
This documentation¶
python -m pip install "zensical==0.0.74"
zensical serve # live preview at http://127.0.0.1:8000
zensical build --strict # the site in site/
The CLI reference page is generated from the binary: after changing commands or flags, run
scripts/gen_cli_reference.py (CI runs it with --check). Screenshots are regenerated with
scripts/screenshots/capture.sh; see Screenshots. The site is deployed to
GitHub Pages from main by .github/workflows/docs.yml.