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

## What you need

Node.js 22 or later, pnpm 10.15.1, and write access to the private [documentation repository](https://gitea.lego-cloud.eu/eldorado-v1/documentation).

## Preview locally

```sh
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

```sh
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](https://pages.apps.lego-cloud.eu/eldorado-v1/documentation/). Pages access follows the platform’s existing authentication policy; a sign-in redirect is not a failed build.