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 ts syntax and a valid filename `ts src/main.ts`
• Code fences require a valid file path to the example .ts file
• 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-cli

For 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 sh syntax
• 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-world

---

Until 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