RUSTICDOCSSearch documentation
DOCSOPEN SOURCE DEVELOPMENTDOCSWRITING DOCUMENTATION

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, then Local Setup and Writing Guidelines. Use Adding Documentation for new routes and Editing Existing Pages 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. Confirm your page appears in navigation and search, and check the setup, examples, and links before opening a pull request.