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 when moving pages. 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 and standalone diagram viewers are non-document HTML routes; no documentation page is exempt.

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.