Logo Vertical Docs

GitHub

Commands

The six commands of vertical-docs, with the docs folder each one reads, the files it writes and the way it fails.

vertical-docs has six commands. Each one except rules takes the docs folder as an argument and uses docs when you name none. A command that fails says what to change and exits with a code other than 0.

vertical-docs init [folder]
vertical-docs dev [folder]
vertical-docs build [folder]
vertical-docs check [folder]
vertical-docs search "<query>" [folder] [--json] [--url <site>]
vertical-docs rules

Run a command

npx vertical-docs runs a command in a repository with or without a package.json, unless the package.json allows only pnpm. You need Node 22.23.4 or later, on macOS or Linux: Windows is not tested. npx asks before it installs the package. npm 10, which comes with Node 22, asks on every run, and npm 11 asks once.

npx vertical-docs check

In a JavaScript project, npm install -D vertical-docs adds the package to the development dependencies. npx vertical-docs then runs that installed version without the question, and a script in package.json can use the short name vdocs:

{
	"scripts": {
		"docs": "vdocs dev"
	}
}

In a project that uses pnpm, pnpm add -D vertical-docs adds the package, with -w in the root of a workspace, and pnpm exec vertical-docs runs a command. init started with pnpm exec names pnpm exec in its last line and in the starter page. In a project whose package.json allows only pnpm, npx stops with EBADDEVENGINES.

pnpm add -D vertical-docs
pnpm exec vertical-docs check

Do not run npx vdocs. The name vdocs on npm belongs to another package, and npx downloads and runs that package in a repository that has not installed vertical-docs.

init

vertical-docs init [folder] writes the docs folder, two workflows and the lines for coding agents in AGENTS.md, and prints each file it writes. Run it in the root of the repository: the workflows go to .github/workflows/ of the current folder, and AGENTS.md goes beside them.

File What it is
docs/content/index.md The first page, a starter tutorial.
docs/docs.config.json The name of the site and the other fields of the site configuration.
docs/public/ Placeholders for the logo, the favicon and the share image.
docs/.gitignore Keeps dist/ and .wrangler/ out of Git.
docs/wrangler.jsonc The settings that deploy the site as a Cloudflare Worker. Replace name with your own before the first deploy.
.github/workflows/docs.yml Runs check on every pull request and every push to main. With the repository variable CLOUDFLARE_ACCOUNT_ID and the secret CLOUDFLARE_API_TOKEN, the workflow then deploys main to the live site and a pull request to its own preview address.
.github/workflows/docs-sync.yml Optional. After a code change on main, an agent on GitHub edits the docs to match and opens one pull request. The agent needs the repository secret ANTHROPIC_API_KEY: without that secret a run does nothing.
AGENTS.md Tells a coding agent that works in the repository, such as Claude Code or Codex, to edit the page when a change to the code changes behaviour the page describes, to follow the writing rules that rules prints, and to run check. It needs no key.

init leaves a file that exists as it is, so a second run writes only the files that are missing. The one exception is an AGENTS.md that exists: init adds its lines at the end of that file, prints Added the docs section to AGENTS.md, and changes nothing else in it. A second run adds nothing: init leaves an AGENTS.md that names vertical-docs check as it is.

In a repository with a formatter such as Prettier, name the docs folder in .prettierignore, or format the folder and name only docs/dist/ there: Prettier does not read docs/.gitignore.

vertical-docs init website names the folder website, in the workflows and in AGENTS.md too. For a folder deeper than one level, add one ../ for each further level to main in its wrangler.jsonc, so that the path reaches node_modules/ in the root of the repository. For packages/docs:

"main": "../../node_modules/vertical-docs/src/worker.ts",

dev

vertical-docs dev [folder] starts a live preview of the docs folder and prints its address, http://localhost:4321/. The preview shows a change to a page or to docs.config.json when you save the file.

Press Ctrl+C to stop the preview. One install of Vertical Docs previews one docs folder at a time: stop the preview of one folder before you start the preview of another.

build

vertical-docs build [folder] writes the site to dist/ in the docs folder: the pages, and the files for agents. The build stops for a page that breaks one of the rules the build checks.

check

vertical-docs check [folder] builds the site, then reads the build and fails for these mistakes in the docs folder:

  • a link or an anchor that points to no page or heading of the site
  • a search result that opens nothing
  • a ### heading with no ## heading above it
  • a line in public/_redirects that points to no page or does not end with 301
  • a missing public/favicon.svg or public/share.png

Each problem is one line that says what to change, and the command exits with code 1:

index.html: link "/guide/" points to no file in dist. Fix the link or add the page.

vertical-docs search "<query>" [folder] prints the sections of the last build that match a query, best first, so run build or check before it. --json prints the results as JSON, and --url <site> searches a deployed site and needs no build. Search from the terminal shows the output of each.

rules

vertical-docs rules prints the writing rules for a page: the file WRITING.md of the package, in the version that runs. The lines init writes to AGENTS.md send a coding agent to this command.

npx vertical-docs rules

The output starts with the title of the rules:

# Writing docs

Update to a new version

The version of Vertical Docs a repository uses is written in its two workflows: in the install step of docs.yml, and as the commit after @ in docs-sync.yml. To move both, delete the two files and run init from the new version, with its number in place of 0.1.0:

rm .github/workflows/docs.yml .github/workflows/docs-sync.yml
npx vertical-docs@0.1.0 init

init writes the two workflows for that version and leaves every other file as it is. Name the docs folder after init when the folder is not docs.

Wrote .github/workflows/docs-sync.yml
Wrote .github/workflows/docs.yml
Next: npx vertical-docs dev docs

A project with vertical-docs in its development dependencies updates the package there as well.

View this page as Markdown