--- title: Getting started description: Install the published tzdocs package, check a folder of Markdown, and build the site, with every command-line flag and its default. slug: /getting-started order: 1 visibility: public redirects_from: [] --- # Getting started 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](/guides/add-a-page/), and [Refusals and findings](/reference/refusals/) explains every message the tool can print. ## Install it The current published version is tzdocs 0.8.0, the npm package [`tzdocs`](https://www.npmjs.com/package/tzdocs). Node.js 20 or later is required, and the package declares no runtime dependency. Installed globally, the tool is the command `tzdocs`. ```text npm install -g tzdocs tzdocs build --source docs --out site ``` Or run it once without installing. ```text 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`. ```text 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](/reference/output/#the-tree)). 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@`, 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`. ```text tzdocs build --source docs --out site --base /docs ``` | Flag | Required | What it does | | --- | --- | --- | | `--source ` | yes | The folder of Markdown files. Subfolders containing an `index.md` become [sections](/concepts/glossary/#section). | | `--out ` | 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 ` | no | The path the site is served under, such as `/docs`, written in front of every [route](/concepts/glossary/#route) in the manifest, the index, and the [whole text](/concepts/glossary/#whole-text). It must start with `/` and follow the [slug rules](/reference/page-source/#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 ` | 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](/reference/output/#the-page-head) 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](/guides/publish-the-site/). | | `--full-text-exclude ` | no | A [tree-relative](/concepts/glossary/#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](/guides/build-for-ai-tools/). | | `--corpus-version ` | 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](/guides/build-for-ai-tools/). | | `--shell ` | no | A complete HTML document with two markers, into which every page is rendered. Default: the tool's [default layout](/concepts/glossary/#default-layout). See [Style the site](/guides/style-the-site/). | | `--home-opening ` | no | An HTML fragment placed before the home page's article content. Default: no fragment. See [Style the site](/guides/style-the-site/). | | `--stylesheet ` | 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](/guides/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](/guides/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. ```text 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](/reference/refusals/#notices) 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](/reference/output/#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`. ```text 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](/guides/check-a-corpus/) is the guide for running the check and correcting what it reports. ## A first corpus A small corpus has this shape. ```text 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](/guides/add-a-page/) walks through the keys, the slugs, the ordering, and the links. ## Related - [Check a corpus](/guides/check-a-corpus/) runs the check and corrects the findings. - [Refusals and findings](/reference/refusals/) lists every message the tool prints, with its exit code, cause, and remedy. - [Output](/reference/output/) describes the generated tree and the four machine files.