# Docs Integrate

> Shared integration checklist for new ZIO library documentation pages. Include after writing any new reference page or how-to guide to ensure it is wired into the site navigation.

- Skill: `zio/docs-integrate` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zio/docs-integrate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zio/docs-integrate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: zio (https://skillmd.com/u/zio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zio/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:

```javascript
// 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:

```bash
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:

```bash
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 <scope>'"), run the `sbt "last <scope>"` it names to get the real error. Common causes:

| Error                                | Likely cause                                            | Fix                                                         |
|--------------------------------------|---------------------------------------------------------|-------------------------------------------------------------|
| `Unknown link '/foo/bar.md'`         | Relative path is wrong or target was renamed            | Update the link to match the actual path under `docs/`      |
| `Reference '...' not found`          | Anchor doesn't match a heading                          | Use lowercase-kebab-case of the heading text                |
| `not found: value Foo`               | Code block is missing an `import` or a previous block   | Add the import or chain via `mdoc` (not `mdoc:reset`)       |
| `value foo is not a member of …`     | API drift since the page was written                    | Re-derive the example against current source                |

### Verify Full Site Build

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

```bash
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.

| Error                              | Likely cause                              | Fix                                          |
|------------------------------------|-------------------------------------------|----------------------------------------------|
| `Doc id not found: foo/bar`        | ID in `sidebars.js` doesn't match the md filename | Check the `id:` frontmatter in the .md file and align `sidebars.js` |
| `Broken link on page …`            | A relative link targets a page that doesn't exist | Fix the path or the target filename         |
| `sidebars.js` not found            | `website/` directory is missing or wrong path | Verify the repo's `website/` layout        |

**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.