Docs Integrate

Documentation Integration Checklist

After writing a new documentation page (reference page or how-to guide), complete these steps to integrate it into the Docusaurus site.

Step 1: Add to sidebars.js

Edit the git-tracked file, not a build artifact. Find it with git ls-files "*sidebars.js" — that path is the one to edit (typically docs/sidebars.js). Never website/docs/sidebars.js: that copy is mdoc's own output, gitignored, and an edit there ships nothing — the build regenerates it and silently discards your change.

Add the page's id to the sidebar in the git-tracked file. Place it in the appropriate category:

• Reference pages: add under the "Reference" category, maintaining alphabetical or logical order.
• How-to guides: add under the "Guides" category. If the category does not yet exist, append a new category entry to the top-level sidebars.docs array (next to "Reference").

Example — a Guides category appended to an existing sidebars.docs array:

// docs/sidebars.js
module.exports = {
  docs: [
    "index",
    {
      type: "category",
      label: "Reference",
      items: [
        "reference/chunk",
        "reference/schema",
        // ... existing reference pages
      ],
    },
    // 👇 NEW category, added by this step
    {
      type: "category",
      label: "Guides",
      items: [
        "guides/guide-id-here",
      ],
    },
  ],
};

After editing, verify the file still parses:

node -e "require('./docs/sidebars.js')" && echo "✓ sidebars.js is valid"

If node reports a syntax error (e.g., unmatched brace, trailing comma without ES2017 support), revert the edit and try again — Docusaurus will fail to start on a malformed sidebar.

Step 2: Update docs/index.md

Add a link to the new page under the appropriate section in docs/index.md:

• Reference pages go under the "Reference Documentation" heading.
• Guides go under a "Guides" heading (create it if missing, after the reference section).

Step 3: Cross-Reference Related Pages

Add links from related existing docs to the new page. Aim for at least two inbound cross-references — one isn't discoverable, three is plenty.

• For each data type or topic the new page covers, find existing documentation pages that mention it and add a "See also" link near the relevant section.
• If you wrote a guide that uses a specific type (e.g., Schema, DynamicOptic), add a cross-reference from the type's reference page to the guide.

Find candidate inbound pages with:

grep -rl "<TypeName or topic keyword>" docs/ | grep -v "<your-new-page-stem>.md"

Step 4: Verify Compilation and Links (Mandatory Gate)

This is a mandatory compilation gate. All code examples in documentation are compile-checked via mdoc.

Check Relative Links

Verify that all relative links in the new page and in any updated pages are correct:

• Internal links use relative paths: [TypeName](./type-name.md).
• Anchor links match actual heading text (Docusaurus converts headings to lowercase kebab-case anchors).
• Run sbt "docs/mdoc --in <path-to-new-page> --out website/<path-to-new-page>" to catch broken mdoc links (they appear as [error] Unknown link '...'). One --in/--out pair per touched file, never unscoped sbt docs/mdoc for this check — --out is the same path prefixed with website/.

If mdoc Fails

If mdoc reports errors, do not commit. Return to the offending page, fix the reported lines, and re-run the same sbt "docs/mdoc --in <path> --out website/<path>" command. Repeat until the run is clean. On a bare "mdoc failed" stack trace with no detail ("stack trace is suppressed; run 'last '"), run the sbt "last <scope>" it names to get the real error. Common causes:

Verify Full Site Build

After mdoc passes, run a full Docusaurus build to catch broken doc IDs, missing sidebar entries, and broken page links:

cd website && yarn build

If yarn build reports errors (e.g., Doc id not found, broken links, sidebar entry missing), fix the reported issues and re-run until the build is clean. Do not commit until this step passes.

If the build fails with many unrelated "Doc id not found" errors, website/docs is likely stale from a previous scoped mdoc run — most pages were never regenerated, so their sidebar ids don't resolve yet. Clean it, run the ONE sanctioned unscoped pass to fill every page (sbt docs/mdoc, no --in/--out — this is the single case where the unscoped command is correct, since the whole tree needs to exist for the build to check it), then retry the build once.

Never create a page to make a link or the build resolve. A link whose target does not exist is removed, not manufactured — a stub page is unreviewed content that ships, and it takes the name the real page will later want: ✅ drop the link, report the gap ❌ write <Type>.md containing "full documentation coming soon" so the sidebar entry stops erroring.

Fix only what your changes broke. If the build surfaces a pre-existing failure on a page you never touched, name it in your report and leave it — never delete a sibling's sidebar entry or write documentation for a sibling module just to force the build green.