Prerequisites

What has to be true before scaffolding a site, and — separately — before a scaffolded site can actually publish to a live URL.

Versions

Tooling that has to be on your machine before running docouture new.

Node.js 24 or newer — the CLI, the UI bundle and both extension packages all declare "engines": { "node": ">=24.0.0" }.
npm or pnpm — docouture new detects one from an existing lockfile/packageManager field, or falls back to how it was itself invoked; --pm overrides the guess.
Docker — only if you keep Kroki diagrams enabled (the default). [mermaid]/[plantuml]/[bpmn]/[excalidraw] blocks render as plain literal text instead if Docker isn’t available, rather than failing the build.

Scaffold

docouture new scaffolds into a repository that already has at least one commit — it does not create one, and Antora reads content from git, so a repository with zero commits builds a site with zero pages. With that in place, run it directly with either package manager, no install step first:

$ pnpm dlx @inditextech/docouture-cli new my-docs

$ npx @inditextech/docouture-cli new my-docs

See Quickstart for what it asks and what it writes, and CLI for every flag.

None of the above is required to try docouture locally: docouture new followed by docouture dev works against a private, unpublished repository just as well. A GitHub repository only becomes necessary once the scaffolded publish workflows need somewhere to run — see Publish below for what a public GitHub Pages site specifically needs.

Publish

Before following Publishing a documentation through to a published site, three things need to be true about this repository and its GitHub settings. None of them are things docouture new can do on your behalf — they all require repository-admin access this CLI never has.

The repository must be public

GitHub Pages serves a gh-pages branch to the public internet on a free plan only for a public repository — a private one needs GitHub Enterprise (GitHub Pages on a paid plan can be restricted to organisation members, but is still not the "publish this to the world" flow docouture-publish.yml assumes). If this repository is private and is meant to stay that way, publishing to GitHub Pages is not the right target — use docouture build and ship build/site some other way instead.

Enable GitHub Pages, serving from `gh-pages`

The gh-pages branch doesn’t exist yet on a brand-new repository, and GitHub Pages can only be pointed at a branch that already exists — so publish once before touching this setting, or the branch picker has nothing to select.

Publish once, to create the gh-pages branch: push to main and let docouture-publish-prerelease.yml run, or publish manually per Publishing a documentation's "Publishing manually" section.
In the repository, go to Settings → Pages.
Under Build and deployment → Source, choose Deploy from a branch.
Under Branch, choose gh-pages and / (root), then save.

Create the `docs/release` label

.github/workflows/docouture-release.yml (scaffolded by docouture new) can cut a release two ways: workflow_dispatch (run it by hand from the Actions tab — works immediately, nothing to set up), or automatically whenever a pull request merges into main carrying a docs/release label.

That label is not created automatically — GitHub does not create labels referenced by a workflow’s if: condition, and docouture new does not call the GitHub API on your behalf. Until the label exists, only the manual workflow_dispatch path works; a PR merged with what would otherwise be the intended label name is a silent no-op, not an error.

Create it once, from this repository:

$ gh label create docs/release --description "Merging this PR cuts a release" --color 0E8A16

Or via the GitHub UI: repository → Issues or Pull requests → Labels → New label, named exactly docs/release. docouture doctor warns (without failing) if it does not find this label, when the gh CLI is available and authenticated.