Getting started #

View this page as Markdown

This page shows how to install the tool and run its two commands, check and build, with every flag the tool accepts. The guides cover the tasks that follow, starting with Add a page, and Refusals and findings explains every message the tool can print.

Install it #

The current published version is tzdocs 0.8.0, the npm package tzdocs. Node.js 20 or later is required, and the package declares no runtime dependency.

Installed globally, the tool is the command tzdocs.

npm install -g tzdocs
tzdocs build --source docs --out site

Or run it once without installing.

npx --package tzdocs tzdocs build --source docs --out site

To add it to a project as a development dependency, run this, then invoke it with npx tzdocs.

npm install --save-dev tzdocs

The project lockfile records the installed version and its integrity hash, so the next install fetches the same bytes. The global and one-time forms create no project lockfile. A version published to the npm registry is never replaced.

The examples in this manual use the installed command tzdocs. With the one-time form, put the npx --package prefix before it.

Verify, upgrade, and remove #

Run tzdocs check --source docs on your corpus, then build it. To view the site, serve the output folder over HTTP and open it in a browser. Opened from disk, the first page shows, but its links open folders rather than pages (Output).

If the command is missing after a global install, check that npm's executable folder is on PATH. The one-time form does not need it.

Upgrade a global installation with npm install -g tzdocs@latest. Roll back to an earlier version with npm install -g tzdocs@<version>, such as tzdocs@0.8.0. In a project, use the same package names with --save-dev, and the lockfile pins the version you chose.

Remove a global installation with npm uninstall -g tzdocs, and a project development dependency with npm uninstall --save-dev tzdocs. Both leave your documentation sources and the generated site in place.

Build the site #

This command builds the folder docs into site, for a site served under /docs.

tzdocs build --source docs --out site --base /docs

Flag	Required	What it does
`--source <dir>`	yes	The folder of Markdown files. Subfolders containing an `index.md` become sections.
`--out <dir>`	yes	A dedicated output folder outside the source tree. A successful build replaces its entire contents. An output folder that overlaps the source, is a link, or contains an input file is refused.
`--base </path>`	no	The path the site is served under, such as `/docs`, written in front of every route in the manifest, the index, and the whole text. It must start with `/` and follow the slug rules. The tool removes one trailing slash and refuses a value that still ends with one, such as `/docs//`, or that breaks the rules. The pages link relatively. Given `--origin`, each page's canonical link and `og:url` tag include it, because they name the page's route. Default: routes start at `/`.
`--origin <url>`	no	The address of the site that serves the pages, such as `https://example.com`: an `http` or `https` address with no path. Each page's canonical link and `og:url` tag give this origin followed by the page's route. The build also writes `sitemap.xml`. The tool removes one trailing slash and refuses any other value. Default: no canonical link, no `og:url` tag, and no sitemap. See Publish the site.
`--full-text-exclude </slug-prefix>`	no	A tree-relative slug prefix, such as `/reference`. Its pages are left out of the whole text and listed under the index's `Optional` heading instead. A prefix that is not a route is a usage error, and the build refuses a prefix that matches no page. See Build for AI tools.
`--corpus-version <text>`	no	The version the corpus describes, written as the manifest's top-level `version`. A blank value is a usage error. Default: the manifest has no version. See Build for AI tools.
`--shell <file>`	no	A complete HTML document with two markers, into which every page is rendered. Default: the tool's default layout. See Style the site.
`--home-opening <file>`	no	An HTML fragment placed before the home page's article content. Default: no fragment. See Style the site.
`--stylesheet <file>`	no	A CSS file written into the tree as `site.css`, its line endings made LF, and linked after the tool's stylesheet on every page. At equal selector specificity, its rules win. Default: no `site.css`. See Style the site.
`--include-hidden`	no	Include pages whose `visibility` is not `public`. By default they are omitted. The flag adds no access control to the generated files.
`--diagrams-as-code`	no	Show every `mermaid` block as code, even where Mermaid is installed, with no script and no notice. Default: draw the diagrams where `npm install mermaid` was run in the folder the build runs in. See Add callouts and diagrams.
`--next-previous`	no	End each page with links to the previous and next pages in the navigation order. Default: off.

A successful build prints one line and exits with code 0. The line gives the page count and the output folder. It also gives any shell, home opening, or stylesheet the build used. With --full-text-exclude, it also gives the number of pages left out of the whole text. The line has this form.

built 13 pages into site with the shell shell.html; 2 pages excluded from the full text

Where pages hold diagrams and Mermaid is not installed, a notice follows on standard error, and the exit code stays 0.

Serve the built site with any static server, for example npx serve site, because its pages link folders that a browser opening files from disk does not resolve.

A build validates everything before it writes, generates the site in a staging folder, and only then replaces the output folder. Publication and recovery says what a failure during the replacement leaves.

Command-line rules #

Relative file and folder arguments resolve from the terminal's current working directory.
Quote a path that contains a space.
Give each value as a separate argument, for example --source "my docs". The tool does not accept the --source=docs form.
Repeating an option is a usage error.
The command has no help, --help, or -h action. An invalid command line prints the usage lines and exits with code 2.
tzdocs --version prints the installed version and exits with code 0.

Check the source #

This command checks the folder docs.

tzdocs check --source docs

The check reads the corpus and writes nothing. It prints one line per finding and exits with code 1 when there is any, or prints one success line and exits with code 0. Add --include-hidden when the build will include hidden pages. The check accepts the build options and ignores them, and it ignores extra positional arguments.

Check a corpus is the guide for running the check and correcting what it reports.

A first corpus #

A small corpus has this shape.

docs/
  index.md
  getting_started.md
  guides/
    index.md
    first_guide.md

Every file needs a title in its front matter and nothing else, because every other key has a default. The file guides/index.md gives the Guides section its name and contains only front matter, because the section contains another page. Add a page walks through the keys, the slugs, the ordering, and the links.

Check a corpus runs the check and corrects the findings.
Refusals and findings lists every message the tool prints, with its exit code, cause, and remedy.
Output describes the generated tree and the four machine files.