# Writing documentation Help first-time users succeed with exact setup steps, copyable examples, expected results, current limitations, and ways to diagnose common failures. Update documentation alongside the engine change whenever engine functionality or scripting behavior changes. For the complete contributor path, begin with [Documentation Overview](https://rustic-game-engine.pages.dev/markdown/open-source/docs/overview.md), then [Local Setup](https://rustic-game-engine.pages.dev/markdown/open-source/docs/local-setup.md) and [Writing Guidelines](https://rustic-game-engine.pages.dev/markdown/open-source/docs/writing-guidelines.md). Use [Adding Documentation](https://rustic-game-engine.pages.dev/markdown/open-source/docs/adding-documentation.md) for new routes and [Editing Existing Pages](https://rustic-game-engine.pages.dev/markdown/open-source/docs/editing-pages.md) for corrections. ## Choose the source - Engine guides live in `docs/` in this repository. Keep the corresponding `Engine/docs/` content in the engine repository accurate too. - Generated API reference content lives in `lib/api-docs.ts`. - Website contributor guides live in `content/`; development and deployment instructions live in `README.md`. `lib/docs.ts` reads these sources at build time. Engine sources use paths such as `docs/Scripting/gameplayActions.md`. Generated sources use the `api:` prefix. Website sources use paths such as `content/my-guide.md` or `README.md`. ## Add a reachable page Each documentation page covers one topic. Keep its setup, examples, parameters, and limitations together, and link to separate topics instead of adding them to the same article. When splitting a broad guide, keep its original URL as a topic index and place the focused pages beneath it, such as `guides/gameplay-actions/paths`. Set each sub-page's `parent` to the original guide's slug and list it immediately after that guide in the catalog. This nests the pages in navigation and adds a link to the parent in their breadcrumbs. Add an entry to the appropriate group in `lib/docs-catalog.ts`. Each entry needs a unique slug, a title, a concise description, and a source: ```ts { slug: "open-source/docs/my-guide", title: "My guide", description: "What readers will learn.", source: "content/my-guide.md" } ``` The catalog supplies static routes, sidebar navigation, previous and next links, and the client-side search index. Put engine usage pages in the engine groups. Under Open Source Development, use Engine source for engine development, Docs for website development, Examples for sample contributions, and Hosting SDK for SDK development. The page above appears at `/docs/open-source/docs/my-guide`. Search indexes the full page content, including code examples and generated API references, at build time. Engine search (`/docs/search`) only returns Engine pages; Open Source Development search (`/docs/open-source/search`) only returns repository guides. The search button and Ctrl/Cmd+K open the search for the current section. ## Link and format content Use a single level-one heading, followed by descriptive level-two or level-three sections. The renderer supports paragraphs, lists, links, inline code, bold text, fenced code blocks, blockquotes, and tables. Use explicit `/docs/...` links for website pages and cross-project references; source-file links can be resolved for cataloged engine documents. ## Verify the result Check the text against the implemented engine behavior. From the docs repository root, run `npm run build`, then preview the exported site as described in [Development & deployment](https://rustic-game-engine.pages.dev/markdown/open-source/docs/development.md). Confirm your page appears in navigation and search, and check the setup, examples, and links before opening a pull request.