documentation/docs/core/maintain.md

title, description, slug

title	description	slug
How to update and publish the site	Preview documentation changes, validate them, and publish through Gitea Actions.	/maintain

What you need

Node.js 22 or later, pnpm 10.15.1, and write access to the private documentation repository.

Preview locally

pnpm install --frozen-lockfile
pnpm start

Open the development server address printed in the terminal. The site uses the /eldorado-v1/documentation/ base path.

Add or change a page

Include title and description frontmatter. Place each page in its owning section and add its document ID to that section’s sidebar:

Section	Content directory	Sidebar configuration
Organization	docs/organization/	sidebars/organization.ts
Strategy	docs/strategy/	sidebars/strategy.ts
Contribution	docs/contribution/	sidebars/contribution.ts
Portal maintenance and reference	docs/core/	sidebars.ts

Keep these content roots disjoint. Preserve existing URLs unless a URL migration is explicitly approved; provide precise redirects for approved moves. Metric details live on individual canonical pages directly under Measurement, alongside shared collection safeguards and the synthetic example. Specific AI initiatives and organizational reporting lines remain subject to agreement. Every published documentation page must have a navigable sidebar entry. Nested references are welcome; hidden documentation is not. Linked category overviews count as entries, but an in-page anchor is not a separate document. Portal-maintenance pages keep their existing /docs/ routes and dedicated sidebar, reachable from Contribution → Portal maintenance.

pnpm verify:build compares all Docusaurus-generated document IDs/routes with resolved sidebar trees (including linked category overviews), checks reachability from the navbar, rejects missing/duplicate entries and unclassified HTML routes, and checks every document’s local links and anchors. The inventory is written to .cache/sidebar-coverage.json. Only the homepage, not-found page, search-results UI, legacy Strategy redirect, exact legacy measurement-contracts hash-aware redirect and standalone diagram viewers are non-document HTML routes; no documentation page is exempt. The metric migration manifest in research/ai-adoption/measurement-migration.json records old anchors, canonical IDs/URLs, implementation status and preserved-contract hashes.

Validate the change

pnpm verify
pnpm typecheck
pnpm build
pnpm verify:build

The build fails on broken internal links. The built-output checks verify routes, locally bundled fonts, search content, and the expected site base path.

Publish

Open a pull request for subsequent changes. Gitea Actions validates pull requests without publishing. Once a change is merged to main, the workflow builds and copies the site to the persistent Pages mount at /gondor-v1-gitea-pages/eldorado-v1/documentation/.

Check the Actions result for that exact commit, then open the published site. Pages access follows the platform’s existing authentication policy; a sign-in redirect is not a failed build.