@sprig-and-prose/tutorial

CLI to run a local tutorial UI for a workspace of markdown tutorials and docs.

How to run

tutorial ui [path?]

• path — Workspace directory (default: current directory).
• Options:
  • --port <number> — Port (default: 3627).
  • --no-open — Do not open the browser.
  • --config <path> — Path to tutorial.config.json.
  • -h, --help — Show help.

Example:

tutorial ui
tutorial ui ./my-tutorials --port 4000 --no-open

Workspace structure

• Tutorials — Any .md file at the workspace root, or any .md file inside a direct subdirectory of the root. Each file should have exactly one # (H1) title and one or more ## (H2) headings; the UI splits on H2 into pages with next/previous navigation.
• Docs — Optional docs/ directory; each .md file is listed under Docs and rendered as a single page (no H2 splitting).
• Assets — Optional assets/ directory; files are served at /workspace-assets/<path>. In markdown, reference images with /workspace-assets/image.png.

Only these directories are ignored when scanning for tutorials: the configured docsDir and assetsDir, plus .git, node_modules, and dist. No other heuristics.

Optional config

Create tutorial.config.json in the workspace root:

{
  "title": "My Tutorials",
  "assetsDir": "static",
  "docsDir": "pages"
}

• title — Optional string; shown in the UI.
• assetsDir — Optional path (relative to workspace) for static assets; default is assets if that folder exists.
• docsDir — Optional path for doc markdown; default is docs if that folder exists.

What you get

After running tutorial ui:

• A calm startup line: workspace path, number of tutorials, docs enabled/none, assets enabled/none, and the URL (e.g. http://localhost:3627).
• The browser opens to that URL (unless you use --no-open).
• The UI shows a left sidebar listing all tutorials and docs; the main panel shows the selected tutorial (H2-split pages with next/prev) or doc (single page). Images under assets load from /workspace-assets/.

No hot reload; this is a static lens over your workspace.