docusaurus-docs-builder
/docusaurus-docs-builder
Use when creating, redesigning, rewriting, or improving a Docusaurus documentation site, docs portal, developer docs, product docs, API docs, guide site, knowledge base, or documentation landing experience, especially when the user wants engaging, attractive, polished, conversion-aware, visual, MDX-powered documentation rather than plain Markdown pages.
- Author
- joeblackwaslike ↗
- Repository
- agent-skills ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 40
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/update.js
What it does and when to use it
Use when creating, redesigning, rewriting, or improving a Docusaurus documentation site, docs portal, developer docs, product docs, API docs, guide site, knowledge base, or documentation landing experience, especially when the user wants engaging, attractive, polished, conversion-aware, visual, MDX-powered documentation rather than plain Markdown pages.
Original author description
Use when creating, redesigning, rewriting, or improving a Docusaurus documentation site, docs portal, developer docs, product docs, API docs, guide site, knowledge base, or documentation landing experience, especially when the user wants engaging, attractive, polished, conversion-aware, visual, MDX-powered documentation rather than plain Markdown pages.
How it works
- Core Behavior
- First Pass
- Documentation Strategy
- Reference Router
- Visual Documentation Rules
- Docusaurus Defaults
- Generated Official Docs
- Completion Gate
- Red Flags
SKILL.md preview
--- name: docusaurus-docs-builder description: Use when creating, redesigning, rewriting, or improving a Docusaurus documentation site, docs portal, developer docs, product docs, API docs, guide site, knowledge base, or documentation landing experience, especially when the user wants engaging, attractive, polished, conversion-aware, visual, MDX-powered documentation rather than plain Markdown pages. metadata: last_updated: "2026-06-11" --- # Docusaurus Docs Builder Build Docusaurus documentation that feels like a polished product surface and still works as serious technical documentation. ## Core Behavior When the user asks for Docusaurus docs, the agent should create a documentation experience with strong information architecture, visual proof, attractive MDX components, runnable examples, search, and verification, even if the source material is messy or text-heavy. ## First Pass Inspect the project before writing: 1. Existing docs site: `docusaurus.config.*`, `sidebars.*`, `docs/`, `src/pages/`, `src/components/`, `src/css/custom.css`, versioned docs, blog, API references. 2. Product surface: package metadata, README, examples, screenshots, demos, changelog, CLI/API entrypoints, install paths. 3. Audience: new user, evaluator, API consumer, contributor, enterprise buyer, operator, or internal team. 4. Primary conversion: install, sign up, copy config, run command, deploy, migrate, integrate, or understand architecture. If there is no Docusaurus site, scaffold the smallest fitting site and explain the chosen structure. ## Documentation Strategy Default shape: 1. **Homepage**: one clear promise, one visual proof, one primary CTA, one secondary CTA. 2. **Docs landing page**: task-oriented entry points, not a file dump. 3. **Getting started**: shortest path to first success. 4. **Guides**: outcome-based workflows. 5. **Concepts**: mental models, architecture, diagrams. 6. **Reference**: APIs, config, CLI, schemas. 7. **Examples**: realistic scenarios with copy-pastable code. 8. **Troubleshooting**: symptoms, causes, fixes. Use progressive disclosure: quick path first, deep details later. When the task is "scaffold docs for this project" or "set up docs like spinup-ts" — for either a new project or an existing repo that lacks real docs — start from `references/project-docs-template.md`. It supplies the full directory tree, `sidebars.ts`, `docusaurus.config.ts`, and every page as a placeholder skeleton, plus an adaptation playbook. Drop it in, then change the details to match the actual project. ## Reference Router Read only what the task needs: | File | When to Read | | --- | --- | | `references/information-architecture.md` | Site maps, sidebar design, docs taxonomy, landing pages | | `references/project-docs-template.md` | Proven, droppable docs scaffold (tree, sidebars, page skeletons) for bootstrapping a new project or revitalizing an existing repo | | `references/visual-mdx-patterns.md` | MDX components, cards, callouts, diagrams, code blocks, before/after sections | | `references/copy-and-conversion.md` | Headlines, CTAs, pain-point framing, page intros, anti-wall-of-text rules | | `references/top-docs-patterns.md` | Best attributes of elite documentation sites and how to apply them | | `references/markdown-mdx-reference.md` | Practical Markdown/MDX syntax and Docusaurus content patterns | | `references/docusaurus-implementation.md` | Config, sidebars, theme, styling, plugins, search, build/deploy | | `references/quality-gate.md` | Build, links, screenshots, search, mobile, accessibility, claims | | `references/generated/manifest.json` | Generated snapshots of current official Docusaurus docs | ## Visual Documentation Rules - No walls of text: turn dense explanations into cards, tabs, diagrams, tables, examples, and callouts. - Every major page needs a visible job: orient, teach, persuade, reference, troubleshoot, or convert. - Use screenshots, terminal demos, Mermaid diagrams, architecture strips, and MDX components where they make understanding faster. - Make navigation task-based: "Install", "Configure auth", "Deploy", "Troubleshoot webhooks" beats internal implementation names. - Put the shortest working example above deeper explanation. - Keep visual polish consistent with the product brand, but do not sacrifice docs usability. ## Docusaurus Defaults - Prefer TypeScript config files when the repo already uses TypeScript. - Use Docusaurus' built-in docs plugin/theme unless a real requirement demands custom routing. - Use MDX for custom visual sections and reusable components. - Use sidebars for guided reading order, not just folder mirroring. - Use admonitions for important notes, not decoration. - Use tabs for platform/package-manager variants. - Use Mermaid for maintainable diagrams when possible. - Use generated static assets under `static/img/` or repo-standard docs assets. Check current generated docs before relying on syntax for config, plugins, MDX behavior, search, or deployment. ## Generated Official Docs Official Docusaurus docs are snapshotted into `references/generated/` by: ```bash node scripts/update.js ``` Use these snapshots when implementation details may have changed. The generated set should include Docusaurus installation, configuration, docs plugin, sidebars, Markdown/MDX, code blocks, admonitions, assets, styling/layout, themes, search, deployment, versioning, i18n, and plugin pages. ## Completion Gate Before saying the docs are done: 1. Run the Docusaurus build or the closest available docs build. 2. Verify key routes, sidebar entries, internal links, images, and code blocks. 3. Confirm first-run instructions are copy-pastable and match package metadata. 4. Check the first screen of the homepage/docs landing page for promise, proof, and action. 5. Report what was verified and any browser/live-render check still needed. ## Red Flags Stop and revise if you catch: - "I'll just convert the README into docs pages." - "The sidebar can mirror the folder tree." - "The homepage can be generic for now." - "This page needs another long explanation." - "The code block probably works." - "The docs build is optional." - "Pretty cards are enough even if users cannot find the answer."
Files in this package (40)
- SKILL.md 6 KB
- agents/openai.yaml 1 KB
- references/copy-and-conversion.md 1 KB
- references/docusaurus-implementation.md 2 KB
- references/information-architecture.md 2 KB
- references/markdown-mdx-reference.md 3 KB
- references/project-docs-template.md 30 KB
- references/quality-gate.md 1 KB
- references/top-docs-patterns.md 5 KB
- references/visual-mdx-patterns.md 2 KB
- references/generated/README.md 2 KB
- references/generated/configuration.md 9 KB
- references/generated/deployment.md 45 KB
- references/generated/docs-create-doc.md 7 KB
- references/generated/docs-introduction.md 4 KB
- references/generated/docs-multi-instance.md 6 KB
- references/generated/i18n.md 7 KB
- references/generated/installation.md 10 KB
- references/generated/manifest.json 8 KB
- references/generated/markdown-admonitions.md 9 KB
- references/generated/markdown-assets.md 6 KB
- references/generated/markdown-code-blocks.md 20 KB
- references/generated/markdown-diagrams.md 4 KB
- references/generated/markdown-features.md 8 KB
- references/generated/markdown-front-matter.md 25 KB
- references/generated/markdown-links.md 4 KB
- references/generated/markdown-tabs.md 9 KB
- references/generated/markdown-toc.md 16 KB
- references/generated/mdx-plugins.md 9 KB
- references/generated/plugin-content-blog.md 24 KB
- references/generated/plugin-content-docs.md 25 KB
- references/generated/plugin-content-pages.md 8 KB
- references/generated/search.md 18 KB
- references/generated/seo.md 10 KB
- references/generated/sidebar.md 1 KB
- references/generated/styling-layout.md 14 KB
- references/generated/swizzling.md 15 KB
- references/generated/theme-classic.md 2 KB
- references/generated/versioning.md 15 KB
- scripts/update.js 6 KB
Versions
The database has no other skills named docusaurus-docs-builder.
Database snapshot: 13.11.2026 · package version b7afbbea0b2f (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 96docusaurus-docs-site
Use when turning repo docs into a Docusaurus site. - 100docusaurus
Build documentation websites with Docusaurus. Use when a user asks to create a documentation site, build a developer portal, set up API docs, create a knowledge base, add versioned documentation, build a static docs site with search, create a blog alongside docs, or migrate from… - 100docusaurus-config-setup
Configure docusaurus config setup operations. Auto-activating skill for Technical Documentation. Triggers on: docusaurus config setup, docusaurus config setup Part of the Technical Documentation skill category. Use when configuring systems or services. Trigger with phrases like… - 100h4tcher-docusaurus-generator
Maintainer skill — generate or refresh the hatch3r project documentation site (Docusaurus 3.x) from this repo's canonical corpus (agents/, skills/, rules/, commands/, hooks/, docs/, plus counts from the public governance/inventory.json). Use when a hatch3r maintainer asks to… - 100sidecar-website
Writing and maintaining the Sidecar Docusaurus documentation site, including page structure, doc authoring, blog posts, styling, images, and deployment workflow. Use when writing documentation, updating the docs site, adding pages or blog posts, or working with Docusaurus configuration. - 90docusaurus-config # IMPORTANT: Keep description on ONE line for Claude Code comp
Use when working with docusaurus.config.js/ts files to validate or modify Docusaurus configuration