Docs Site skill for Claude Code
Docs people can navigate, search and trust. Claude designs the information architecture before touching a framework: it audits existing pages and support questions, groups guides by reader job, and caps the sidebar at three levels. It then picks Starlight, Docusaurus, MkDocs or VitePress for your situation, wires search, redirects for every moved URL and versioning only if users need it, and sets up strict builds, link checks and PR previews.
- name
docs-site - size174 lines · ≈1,850 tokens
- files2
- licenseMIT
- updated
What Claude sees before loading it
This description is the only part of the skill that sits in context all the time. Claude reads it to decide when to load the full playbook below.
description: Plans and builds documentation sites with Starlight, Docusaurus, MkDocs, or VitePress — framework choice, information architecture by reader task and Diátaxis type, sidebar and landing-page design, search, versioning only when needed, redirects for moved pages, docs-as-code review, strict builds, link checking, and PR previews. Use when creating or restructuring a docs site, migrating between docs frameworks, adding search or versioning, or when users cannot find pages in existing docs.Try asking
- Set up a Starlight docs site for our SDK with guides, reference and a quickstart
- Users can't find anything in our Docusaurus docs. Restructure the sidebar
- Migrate our MkDocs site to Starlight without breaking existing URLs
Use it when
- Creating a new documentation website
- Restructuring navigation in existing docs
- Migrating between docs frameworks
- Adding search, versioning, or redirects
Skip it when
- You need to write or fix the content of individual pages, use technical-writing instead
- You only need a single README, use readme-writer instead
- You are converting Markdown to PDF or DOCX, use markdown-publishing instead
How to check the result
The strict build and link checker pass, every old URL returns 200 or redirects, and five real support-ticket tasks are findable within a minute each.
The common mistake it prevents
Renaming or moving doc files without adding redirects, which silently breaks every inbound link from search results, blog posts and support macros.
--- name: docs-site description: Plans and builds documentation sites with Starlight, Docusaurus, MkDocs, or VitePress — framework choice, information architecture by… license: MIT ---
A docs site is done when a new reader reaches the right starting page in one click from the landing page, any page is findable by search with the words users actually type, no link is broken, moved pages redirect, and the build fails in CI on a broken link or invalid page.
Ground rules
- Information architecture before framework. A great theme does not fix a sidebar that mirrors the org chart.
- Organize by what readers are trying to do, not by internal component names.
- Docs live next to the code (docs-as-code), change in the same PR as the feature, and
have owners (
CODEOWNERS). - Every URL is permanent once published. Moving a page means adding a redirect.
- Version docs only when users genuinely run multiple versions at once. Versioning multiplies maintenance.
Choose a framework
| Situation | Choice | Why |
|---|---|---|
| New docs, JS/TS ecosystem, content-first | Starlight (Astro) | Fast static output, built-in Pagefind search, i18n, good defaults, MDX/Markdoc |
| Need React components heavily, versioned docs, blog, large plugin ecosystem | Docusaurus 3 | Built-in versioning, mature plugins, Algolia DocSearch integration |
| Python project, Markdown-only authors | MkDocs + Material theme | Simple YAML config, strong search, admonitions; note Material for MkDocs moved to maintenance mode in late 2025 with its team building Zensical, so evaluate Zensical for brand-new Python-ecosystem sites |
| Vue project or minimal docs next to a library | VitePress | Very fast, simple config |
| No build pipeline wanted, budget available | Hosted (Mintlify, GitBook, ReadMe) | Trade control and portability for speed |
Setup commands and config skeletons for each are in references/framework-setup.md; read it when scaffolding, migrating, or configuring search, versioning, and redirects.
Workflow
- [ ] 1. Audit existing content and reader questions (support tickets, search logs)
- [ ] 2. Design the IA: top-level sections, sidebar, landing page
- [ ] 3. Choose framework; scaffold; set strict build and link checks
- [ ] 4. Migrate or write content with a standard page template
- [ ] 5. Configure search, redirects, versioning (if needed), analytics, feedback
- [ ] 6. CI: build, lint, link check, preview deploys per PR
- [ ] 7. Verify findability with real tasks1. Audit
- List every existing page with: type (tutorial/how-to/reference/explanation), owner, last updated, traffic (if analytics exist), and keep/merge/rewrite/delete.
- Collect the top 20 reader questions from support tickets and site search queries with zero results. These drive IA and page titles.
2. Information architecture
Default top level (adapt names to your product):
Get started quickstart, installation, core concepts (tutorial + explanation)
Guides task-oriented how-tos grouped by job ("Payments", "Users")
Reference API, CLI, config, generated where possible
Concepts explanations: architecture, how X works
Resources changelog, migration guides, FAQ, supportRules:
- 5–7 top-level sections maximum; sidebar depth ≤ 3 levels.
- Group guides by user job, not by internal service.
- Page titles are what users search: “Set up SSO with Okta”, not “Okta Integration Module”.
- Landing page routes by intent: 3–4 large entry points (Quickstart, Guides, API reference, Concepts) plus search front and center. No marketing hero.
- Every page ends with “Next steps” links; reference pages link to related guides.
4. Page template (frontmatter)
---
title: Set up SSO with Okta
description: Connect Okta to your workspace with SAML so members sign in with their company account.
sidebar:
order: 3
---
Short statement of the outcome and prerequisites.
## Steps ...
## Verify ...
## Troubleshooting ...
## Next steps ...description feeds search snippets and social previews: write it for every page
(~150 characters). Use technical-writing for page-level writing rules.
5. Search, redirects, versioning
- Search: Starlight ships Pagefind (static, no service). Docusaurus commonly uses Algolia DocSearch (free for open-source docs) or a local search plugin. MkDocs Material has built-in client-side search.
- Tune search with synonyms for common alternate terms (e.g. “login” → “sign in”) where the engine supports it, and fix titles rather than relying on synonyms.
- Redirects: every moved or deleted URL maps to its best replacement. Keep a redirects file under version control and review it in PRs that move pages.
- Versioning: if needed, keep “latest” as the default, show a banner on old versions, and limit to supported versions (e.g. current + previous major).
6. CI pipeline
# .github/workflows/docs.yml (excerpt)
on: { pull_request: { paths: ["docs/**", "astro.config.mjs", "package.json"] } }
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 22, cache: npm }
- run: npm ci
- run: npm run build # fails on invalid frontmatter/broken internal links where configured
- run: npx markdownlint-cli2 "src/content/docs/**/*.{md,mdx}"
- uses: lycheeverse/lychee-action@v2
with: { args: "--no-progress --offline dist" }- Make the build strict: Docusaurus
onBrokenLinks: 'throw', MkDocsmkdocs build --strict, Starlight content schema validation plus a link checker (e.g. the communitystarlight-links-validatorplugin or lychee on the output). - Preview deploys per PR (Netlify, Vercel, Cloudflare Pages) so reviewers read rendered pages.
- Optional: Vale for style (
vale src/content/docs), spell check with a project word list.
Gotchas
- Sidebars autogenerated from folders expose internal structure and odd ordering; set explicit order and labels.
- Renaming files changes URLs in most frameworks; add redirects in the same PR.
- MDX components make content hard to migrate later; use them for genuinely interactive pieces only.
- Versioned docs where fixes land only in “next” leave old versions wrong forever; decide the backport policy.
- Site search that indexes the changelog and blog drowns how-to results; scope or weight the index.
- Large images and GIFs make docs slow; compress and set dimensions.
Verification
- Findability test: give 5 real tasks from support tickets to someone new; they find the right page via navigation or search within 1 minute each.
- Build is strict and green; link check passes on the built output.
- Every URL from the old site (crawl or sitemap) returns 200 or redirects.
- Lighthouse on a typical page: performance ≥ 90, accessibility ≥ 95.
- Zero-result search queries reviewed monthly (if analytics available) and turned into titles, synonyms, or new pages.
Output contract
## Docs site plan
Framework: Starlight (reason)
IA: Get started / Guides (Payments, Users, Webhooks) / Reference / Concepts / Resources
Landing page entry points: Quickstart, Guides, API reference, Concepts
Search: Pagefind; synonyms: login→sign in
Versioning: none (single hosted version)
Redirects: 34 mapped from old site (redirects file)
CI: build + markdownlint + lychee + PR previews
Content actions: 18 keep, 9 rewrite, 6 merge, 4 deleteBundled files
Loaded only when a step in the skill needs them. Review them here before installing.
references/framework-setup.md
# Framework setup reference
Read this when scaffolding a docs site, migrating frameworks, or configuring search,
versioning, and redirects. Check each framework's current docs for version-specific
details before pinning config; options below reflect 2025–2026 stable releases.
## Starlight (Astro)
```bash
npm create astro@latest -- --template starlight
npm run dev # local preview
npm run build # static output in dist/
```
Content lives in `src/content/docs/`; the file path becomes the URL.
```js
// astro.config.mjs
import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";
export default defineConfig({
site: "https://docs.example.com",
redirects: {
"/guides/old-sso": "/guides/sso-okta",
},
integrations: [
starlight({
title: "Example Docs",
social: [{ icon: "github", label: "GitHub", href: "https://github.com/example/repo" }],
editLink: { baseUrl: "https://github.com/example/repo/edit/main/" },
sidebar: [
{ label: "Get started", items: [{ slug: "start/quickstart" }, { slug: "start/install" }] },
{ label: "Guides", autogenerate: { directory: "guides" } },
{ label: "Reference", autogenerate: { directory: "reference" } },
],
}),
],
});
```
- Search: Pagefind is built in and indexes at build time.
- Versioning: not built in; community plugins exist, or deploy versions to separate
paths/subdomains.
- Link validation: community plugin `starlight-links-validator`, or lychee on `dist/`.
- i18n: `locales` option in the Starlight config; content under `src/content/docs/<lang>/`.
## Docusaurus 3
```bash
npx create-docusaurus@latest my-docs classic --typescript
npm run start
npm run build # output in build/
```
```ts
// docusaurus.config.ts (excerpt)
const config = {
url: "https://docs.example.com",
baseUrl: "/",
onBrokenLinks: "throw",
presets: [["classic", { docs: { sidebarPath: "./sidebars.ts", editUrl: "https://github.com/example/repo/edit/main/" } }]],
plugins: [
["@docusaurus/plugin-client-redirects", { redirects: [{ from: "/guides/old-sso", to: "/guides/sso-okta" }] }],
],
themeConfig: {
algolia: { appId: "YOUR_APP_ID", apiKey: "SEARCH_ONLY_KEY", indexName: "example" },
},
};
export default config;
```
- Versioning: `npm run docusaurus docs:version 2.0` snapshots `docs/` into
`versioned_docs/version-2.0/`. Configure `lastVersion` and `onlyIncludeVersions` to
limit what builds.
- Sidebars: `sidebars.ts` with explicit categories; avoid relying only on autogenerated
order.
- Search alternatives to Algolia: community local-search plugins.
## MkDocs with Material theme
```bash
python3 -m venv .venv && . .venv/bin/activate
pip install mkdocs-material
mkdocs new .
mkdocs serve
mkdocs build --strict # fail on warnings such as broken internal links
```
```yaml
# mkdocs.yml
site_name: Example Docs
site_url: https://docs.example.com/
repo_url: https://github.com/example/repo
edit_uri: edit/main/docs/
theme:
name: material
features: [navigation.sections, navigation.instant, search.suggest, content.code.copy]
plugins:
- search
- redirects:
redirect_maps:
guides/old-sso.md: guides/sso-okta.md
nav:
- Get started: [start/quickstart.md, start/install.md]
- Guides: [guides/sso-okta.md]
- Reference: [reference/cli.md]
markdown_extensions: [admonition, pymdownx.superfences, pymdownx.tabbed, toc]
```
- Redirects need `pip install mkdocs-redirects`.
- Versioning: `mike` (`pip install mike`), which deploys each version to the gh-pages
branch: `mike deploy --push --update-aliases 2.0 latest` then `mike set-default --push latest`.
- Material for MkDocs entered maintenance mode in late 2025; its team is building
Zensical as the successor. Existing sites keep working; for new sites, compare both.
## VitePress
```bash
npx vitepress init
npm run docs:dev
npm run docs:build
```
Config in `.vitepress/config.mts` with `themeConfig.nav`, `themeConfig.sidebar`, and
`themeConfig.search: { provider: "local" }` for built-in local search.
## Migration checklist (any framework to any framework)
- [ ] Crawl or export the old sitemap; save the URL list.
- [ ] Convert content (Markdown mostly ports; framework-specific components and
admonition syntax need rewriting).
- [ ] Map every old URL to a new one; generate the redirects config from the map.
- [ ] Recreate frontmatter (`title`, `description`, sidebar order).
- [ ] Rebuild search config and synonyms.
- [ ] Run link check on the new build; then check every old URL returns 200 or 301.
- [ ] Keep the old site read-only until analytics show traffic has moved.
About this skill
Written and maintained by the Claude Skills editors to the same editorial standard as every skill in the directory: a selective trigger, a real workflow, known pitfalls and a verification step. First published , last updated . MIT licensed.