# Docs Integrate

> Integration checklist for new ZIO docs pages. Handles sidebar wiring, index.md linking, and compilation gate (mdoc + Docusaurus build). Cross-referencing is handled separately by the integrate workflow (Phase 2).

- **Type:** Skill
- **Install:** `agentstack add skill-zio-zio-skills-docs-integrate`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [zio](https://agentstack.voostack.com/s/zio)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [zio](https://github.com/zio)
- **Source:** https://github.com/zio/zio-skills/tree/main/writer-assistant/skills/docs-integrate

## Install

```sh
agentstack add skill-zio-zio-skills-docs-integrate
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Docs Integration Checklist

After writing new doc page (ref page, tutorial, how-to), complete all steps.

## Step 1: Add to `sidebars.js`

Add page `id` to `docs/sidebars.js`. Correct category:

- **Ref pages** → `"Reference"` category, alphabetical/logical order
- **How-to guides** → `"Guides"` category. Missing category → append new entry to `sidebars.docs` array
- **Tutorials** → `"Tutorials"` category. Missing → append

Example — Guides category appended:

```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'],
    },
  ],
};
```

Verify parses:

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

Syntax error → revert + retry. Malformed sidebar → Docusaurus fails to start.

## Step 2: Update `docs/index.md`

Add link under correct section:

- Ref pages → "Reference Documentation" heading
- Guides → "Guides" heading (create after ref section if missing)
- Tutorials → "Tutorials" heading (create if missing)

## Step 3: Verify Compilation + Links (Mandatory Gate)

**Mandatory gate.** All code examples compile-checked via mdoc.

### Check Relative Links + Compile

- Internal links → relative paths: `[TypeName](./type-name.md)`
- Anchor links → match heading text (Docusaurus converts to lowercase kebab-case)
- Call `run_mdoc` tool with the new page path:

```
run_mdoc({ paths: [""] })
```

Returns `{ success, errorCount, errors[] }`. Do **not** commit if `success: false`. Fix each entry in `errors[]` → re-call `run_mdoc` → repeat until `success: true`.

### Verify Full Site Build

After mdoc passes, call `build_website` tool:

```
build_website({})
```

Returns `{ success, errorCount, errors[] }`. Do **not** commit if `success: false`. Fix each entry in `errors[]` → re-call `build_website` → repeat until `success: true`.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [zio](https://github.com/zio)
- **Source:** [zio/zio-skills](https://github.com/zio/zio-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zio-zio-skills-docs-integrate
- Seller: https://agentstack.voostack.com/s/zio
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.