Add your docs

docs.gala.com is assembled from what each team publishes from its own repository. Nobody copies files into this site: your CI publishes, the site fetches, and the next build shows it. Pick the path that fits what you have.

HTTP API​

The API reference (pages per tag, every parameter, request and response tables, raw JSON and YAML, a markdown twin and a full-text file for AI tools) is generated from your spec. There is no markdown to write.

1. Make the spec worth reading. Every operation needs a unique operationId, a tags entry (each tag becomes a page), a one-line summary, and descriptions on parameters and fields. The build fails on a missing or duplicate operationId, and on any value that looks like a secret.

2. Publish it from your main branch. Upload the spec to your project's generic package registry as package <service>-openapi, version main. The file name matters:

curl --fail --request PUT \
  --header "JOB-TOKEN: $CI_JOB_TOKEN" \
  --upload-file openapi.json \
  "$CI_API_V4_URL/projects/$CI_PROJECT_ID/packages/generic/<service>-openapi/main/openapi.json"

openapi.yaml and meta.json ({"commit": "<sha>", "generatedAt": "<iso time>"}) are optional and are fetched when present.

3. Let the docs build read it. In your project, open Settings, CI/CD, Job token permissions, and add gala-games/defi/gala-monorepo to the allowlist. Without it the fetch answers HTTP 404 or 403 and the service is skipped (the build prints which one).

4. Add one entry to apps/docs/site.config.json in gala-monorepo, under openapi.services, and open a merge request:

{
  "id": "your-service",
  "title": "Your Service",
  "required": false,
  "source": { "gitlab": "gala-games/<your>/<project>", "package": "<service>-openapi/main" }
}

id becomes the URL (/openapi/your-service/). Set required to true once the service should fail the build when its spec is missing. A tag that only exists for one old client can be listed under legacyGroups to sit in a collapsed "Legacy routes" section.

When the merge request lands, the site shows your API in the API reference menu, the footer, search, llms.txt and llms-full.txt. Your spec is re-fetched on every site build, so a main push in your repo shows up at the next docs deploy without any change here.

SDK or tool guides​

Guides, tutorials and a generated API reference come from a docs bundle that @gala-games/docs-tools builds. Install it as the package README describes (packages/docs-tools/README.md), then:

1. Write docs/docs.json listing your pages. Each page has a slug, a source markdown file, a title, a one-sentence summary, a section, an order and a kind such as guide or concept.
2. Write the pages to the agent-quality rules the build enforces: a front-matter summary, an explicit {#anchor} on every heading, a language on every code fence.
3. Put your code samples in fences and let the build type-check them against your package's real exports, so a sample cannot drift from the API.
4. Add an agents.md page: which job each export does, task recipes, the invariants, and every error code with its fix. It is what AI tools read first.
5. Run gala-docs build and gala-docs check, then publish the bundle. Today bundles are stored in gala-monorepo's package registry and listed in packageOrder of site.config.json, so a new package is added with a short merge request there. Open it early and we will set up the CI job with you.

Markdown only​

Your docs stay in your repository. The site clones the folder on every build, so a merge request to your own repo is how you change your pages, and nothing is copied here.

1. Write the pages. Put .md files in a docs/ folder (or any folder you name in step 4). Each page needs:

• a title: title: in the front matter, or a first # Heading;
• a summary: summary: in the front matter, or a first paragraph (it becomes the search and llms.txt description);
• a language on every code fence (bash, ts, json, text).

Headings get stable anchors automatically. A page links to another page of the folder with a normal relative link ([restart](./runbooks/restart.md#steps)); the build rewrites it to the site address. A link that is not another .md page of the folder, or an image stored in the repository, fails the build: link a full https:// address instead.

2. Choose the order (optional). Without a nav.json the pages are ordered for you: README.md first, then the other files, then each subfolder as its own sidebar section. To control it, add docs/nav.json; every page must be listed:

{
  "sections": [
    { "title": "Start here", "pages": ["README.md", "getting-started.md"] },
    { "title": "Runbooks", "pages": ["runbooks/restart-worker.md"] }
  ]
}

A page's address comes from its file name in lower case (runbooks/restart-worker.md becomes /<your-id>/latest/runbooks/restart-worker), so rename files rather than titles to change it.

3. Let the docs build read your repository. In your project open Settings, CI/CD, Job token permissions, and add gala-games/defi/gala-monorepo to the allowlist. Without it the clone fails and the build says so.

4. Add one entry to apps/docs/site.config.json in gala-monorepo, under guides.sources, and open a merge request:

{
  "id": "your-team",
  "title": "Your team handbook",
  "summary": "One sentence on what these docs are for.",
  "source": { "gitlab": "gala-games/<your>/<project>", "ref": "main", "path": "docs" }
}

id becomes the address (/your-team/latest/). ref and path default to main and docs. Set "required": true only when the site should fail to deploy without your docs.

The merge request pipeline builds the site with your entry and fails with every problem listed as file:line (a missing summary, a fence without a language, a link to nothing), so you fix them in your repository before anything merges. After the merge, your docs appear under Guides in the menu and footer, in search, in llms.txt and llms-full.txt.

Staying current. The site reads the tip of your branch at each docs deploy (every push to gala-monorepo main). If your repository becomes unreadable or invalid later, the site keeps deploying without your section and the build log names the reason.

Limits today: .md files only (no MDX), no images from the repository, no versions (always the branch tip), and no sections outside the folder you name.

What readers and tools get​

Everything you publish gets the same treatment: sidebar and search scoped to your section, a raw markdown twin of every page (append .md), an entry in /llms.txt and the full-text files, and link checking on every build, so a broken link in your docs fails the pipeline rather than reaching readers.