> For the complete documentation index, see [llms.txt](https://suigar.gitbook.io/suigar-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://suigar.gitbook.io/suigar-docs/seo/subprojects/docs-site.md).

# Docs site

Last reviewed: 2026-07-13

Applies to public documentation content in `docs/public/` and the `docs-site/` implementation.

## Role

Docs should answer mechanics, integration, and protocol questions clearly. Blog posts can explain context and product stories, but docs should remain the canonical place for how things work.

## Rules

* Keep docs accurate, current, and linked from relevant app/blog pages.
* Use descriptive headings that answer real user, builder, and partner questions.
* Prefer stable URLs for public developer docs: SDK now, MCP docs when they are ready.
* Avoid duplicating full blog narratives. Link to blog for launch context or editorial framing.
* Avoid private implementation detail unless it is intentionally public developer documentation.
* When product mechanics change, update docs and any linked SEO/blog guidance in the same work.
* Mainnet docs must publish `robots.txt` with `Allow: /` and exactly one sitemap directive: `https://suigar.com/sitemap_index.xml`.
* Docs sitemap post-processing must require `lastmod` and remove ignored `changefreq`/`priority` hints.
* The production build must finish with `check:seo`, including rendered HTML/canonical validation for every sitemap URL.
* Non-mainnet docs should render `noindex,nofollow`, publish blocking `robots.txt`, and avoid advertising a sitemap.
* Legacy docs subdomains should 301 path-preserving to the matching `/docs` path on the frontend host.

## Current Anchors

* Docusaurus canonical URL and non-mainnet robots metadata: `docs-site/docusaurus.config.mjs`.
* Generated docs copy and sidebar source: `docs-site/scripts/prepare-docs.mjs`, `docs/public/SUMMARY.md`, and `docs-site/sidebars.cjs`.
* Internal SEO, engineering, migration, and AI operating docs stay outside `docs/public/` so they are never copied into the public docs-site build.
* Docs-site CI watches `docs/public/**` instead of all `docs/**`, so internal documentation changes do not trigger docs deploy checks.
* Robots/sitemap post-processing and build gate: `docs-site/scripts/write-seo-assets.mjs` and `docs-site/scripts/check-seo.mjs`.
* `/docs` frontend path routing and legacy subdomain redirects: `infrastructure/main.tf` and `infrastructure/static-sites.tf`.
* Deploy verification: `.github/workflows/docs-site.yaml`.

## Target Live State

Implemented in repo on 2026-05-29; verify after the next infra and docs deploy:

* `https://suigar.com/docs/` returns HTTP 200 directly.
* `https://suigar.com/docs/robots.txt` allows crawling and advertises `https://suigar.com/sitemap_index.xml`.
* `https://suigar.com/docs/sitemap.xml` contains public SDK docs only until MCP docs are added.
* `https://suigar.com/docs/seo/`, `https://suigar.com/docs/engineering/`, and other internal docs paths return HTTP 404 so private tracking and implementation notes do not become public search inventory.
* Legacy docs subdomain requests 301 to the matching `https://suigar.com/docs/` path.
* Search Console URL Inspection should be re-run for `https://suigar.com/docs/` after deployment.
* The shared production sitemap audit is available manually and through `ENABLE_LIVE_SITEMAP_AUDIT=true`, but is disabled in normal docs CI.

## AI Search/GEO Notes

* Write concise definitions that can be extracted by AI answer engines.
* Keep entity names consistent: Suigar, Sui, SweetHouse, VIP, referrals, rakeback, game names, and SDK.
* Add examples and direct answers where they help users complete a task.

## Next Improvements

* Add a regression check that fails if private docs prefixes reappear in the public docs sitemap.
* Add structured content templates for game mechanics and SDK pages.
* Cross-link docs and blog posts through deliberate "learn more" paths.