// 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.
| name | docs-integrate |
| description | 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. |
| allowed-tools | Read, Edit, Glob, Grep, Bash(git:*) |
After writing a new documentation page (reference page or how-to guide), complete these steps to integrate it into the Docusaurus site.
sidebars.jsAdd the page's id to the sidebar in docs/sidebars.js. Place it in the appropriate category:
"Reference" category, maintaining alphabetical or logical
order."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.
docs/index.mdAdd a link to the new page under the appropriate section in docs/index.md:
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.
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"
This is a mandatory compilation gate. All code examples in documentation are compile-checked via mdoc.
Verify that all relative links in the new page and in any updated pages are correct:
[TypeName](./type-name.md).sbt "docs/mdoc --in <path-to-new-page>" to catch broken mdoc links (they appear as [error] Unknown link '...').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>" command. Repeat until the run is clean. 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 |
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.
| 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 |
Stop and consult this skill whenever your response would involve any fact or code related to ZIO HTTP. Covers: installation and setup, routing (Routes, RoutePattern, PathCodec), handlers and HandlerAspect, the declarative Endpoint API and HttpCodec, client and server configuration, middleware, request/response/headers/cookies, WebSockets, Server-Sent Events, Body and binary codecs, form data, template DSL, OpenAPI documentation and code generation, authentication (basic, digest, bearer, JWT, OAuth, WebAuthn), TLS/SSL/mTLS, testing, ZIO Config integration, Datastar/HTMX integration, migration, and any ZIO HTTP library versions or dependencies. Trigger this even for coding tasks that import zio.http, content that mentions ZIO HTTP features or types, or comparisons involving ZIO HTTP. Any time you would otherwise rely on memory for ZIO HTTP details, verify here instead — your training data may be outdated or wrong.
Stop and consult this skill whenever your response would involve any fact or code related to ZIO core or the ZIO ecosystem. Covers: ZIO effects and type aliases (ZIO, Task, UIO, UEffect), fibers and fiber management, concurrency primitives (Hub, Queue, Ref, Semaphore), Software Transactional Memory (STM), ZIO Streams (ZStream, ZSink, ZPipeline, ZChannel), ZIO Test framework and test utilities, ZLayer and dependency injection patterns, error management and error types, scheduling and retries, resource management and scoping, ZIO Config, ZIO Schema, ZIO JSON, ZIO Kafka, and all official ZIO libraries and integrations. Trigger this for any ZIO coding task, type signatures, library features, architectural patterns, or comparisons involving ZIO. Any time you would otherwise rely on memory for ZIO details, verify here instead — your training data may be outdated or wrong.
Scans merged GitHub PRs (from latest commit back to an upstream base ref) and produces a documentation-coverage audit report. Processes 20 PRs per batch and asks before continuing to the next batch. Skips PRs already checked in previous runs using a persistent state file. For each new PR, determines whether documentation is required based on labels, changed files, and content signals, then checks whether docs exist and grades coverage using four rubric levels: Well Documented, Partially Documented, Stub, or Not Documented. Outputs a focused report showing only PRs that require docs, sorted by coverage gap severity. Use this skill whenever the user wants to know which merged PRs are missing documentation, wants a documentation debt audit, or asks "what needs to be documented?", "which PRs have no docs?", or similar coverage questions. Invoke it even if the user just says "doc audit" or "show me undocumented changes."
Critique and fix existing documentation files using an automatic review loop. Spawns critics to review docs and makers to fix issues. Iterates until approved or max 3 rounds. Handles single files or directories. Works with available tools.
Shared reference for mdoc code block modifiers and Docusaurus admonitions used across ZIO library documentation skills. Include when writing any documentation that contains Scala code blocks.
Prose style rules for documentation (reference pages, how-to guides, tutorials). Use this skill whenever writing or editing documentation to ensure consistency, clarity, and professionalism across all docs.