> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vegalake.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing to the documentation

> Preview, validate, and safely update VegaLake guides and generated API references.

# Documentation development

This author-facing page is intentionally excluded from customer navigation. The repository README is the canonical contributor entry point.

## Preview locally

Install the pinned dependencies with `PUPPETEER_SKIP_DOWNLOAD=true npm install`. The npm scripts use the project-local Node 22 binary automatically, even if the system Node version is newer. Then run:

```bash theme={null}
npm run dev
```

The local Mintlify preview reports its URL after startup.

## Page conventions

* Use `.mdx` with `title` and `description` frontmatter.
* Start content with one clear H1 and organize procedures with descriptive H2 headings.
* Prefer plain Markdown; add supported Mintlify components only when they improve scanning.
* Link local pages with absolute documentation paths such as `/vegaflow/connections`.
* Keep public navigation in `docs.json`; every listed page must exist.
* Define a term before using an acronym or backend-specific name.
* Describe observable product behavior, not internal implementation trivia.

## Update API references

Do not edit files under `api-reference/specs` by hand. Run:

```bash theme={null}
npm run sync:openapi
npm test
npm run sync:openapi -- --check
```

Inspect the diff for public operation additions/removals, authentication changes, server roots, and accidental exposure of internal or operator contracts.

## Validate before publishing

```bash theme={null}
npm run check
```

This verifies deterministic OpenAPI generation, documentation contracts, a strict Mintlify build, and broken links. Redact all credentials and secret values from examples and diagnostic output.