Tutorial Runner
The zkApp Tutorials at zkApp Tutorials use a tutorial runner to verify TypeScript code. See tutorial-runner.ts in GitHub.
The tutorial checker verifies the TypeScript code in code blocks:
- Code fences for TypeScript require
tssyntax and a valid filename`ts src/main.ts` - Code fences require a valid file path to the example
.tsfile - Code snippets must be valid TypeScript code
- Line numbers and command prompts (
$) are stripped by the copy-to-clipboard action present on the published doc - The zkApp CLI installation command in Tutorial 1 needs to execute to get things started.
- The tutorial runner goes through the tutorial file (.mdx) and collects all code snippets, writes them into the specified file and executed scripts to run them
- You can use comments to "hide" code from being rendered, while still allowing the tutorial runner to pick it up
The tutorial runner requires the zkApp CLI install command:
$ npm install -g zkapp-cliFor example:
To prevent the verification when you want to show generic TypeScript code blocks, like examples of using an API, use an ignore flag:
In addition to verifying the TypeScript code, the tutorial checker can also run shell commands and check for the returned status code to be successful:
- Shell fences require a
shsyntax - Shell snippets require a '$' before the command to tell the tutorial runner to run the command. (It will not verify the output).
For example:
To troubleshoot, you can run the tutorial runner locally by installing act and running the following command:
act --job=<tutorial>
# Run tutorial 1: act --job=hello-worldUntil all of the current work is completed, the tutorial runner checks only the first tutorial, see the CI config: https://github.com/o1-labs/docs2/blob/aeeafe9f0fc5cea76cc82ff34a024eee6d1c21e2/.github/workflows/test-tutorials.yml#L19
The runner script provides some documentation at the top: https://github.com/o1-labs/docs2/blob/5ef5ad27673af2de555c5c938bd0d8f93bdd73b8/scripts/tutorial-runner.ts