kindlings-doc-maintenance

To test executable code snippets in markdown documentation, you can automate validation using scala-cli-md-spec to run snippet tests defined in scripts/test-snippets.scala, ensuring deterministic execution across CI and local runs.

Verifying deterministic output for documentation code snippets requires adding // expected output annotations inside your markdown files. This directive checks the actual snippet execution against the expected preview to ensure reliable documentation.

Yes, you can run documentation snippet tests locally and in a CI pipeline. The testing workflow is designed to validate markdown files in docs/user-guide consistently across both environments using a reproducible test pipeline.

The best way to maintain executable code snippets in a user guide is to formalize the writing and testing process by applying automated verification directives and template variable handling, keeping documentation accurate and verifiable across updates.

Yes, scala-cli-md-spec is required to automate markdown snippet testing. It provides the underlying testing workflow that validates files matching docs/user-guide/**/*.md and executes the snippet tests defined in your test scripts.

Documentation code snippets failing in CI but passing locally often indicates a lack of output verification directives or unhandled template variables. Integrating deterministic output checks with // expected output annotations ensures reproducible test pipeline results.