Search the docs, videos, blog, apps, teams, skills and release notes.
At a glance
What it is
Expert guidance for building documentation sites with Docusaurus, MkDocs, and VitePress, covering setup, customization, content organization, search, versioning, and deployment.
A skill is a written procedure a bot loads when a job calls for it. This one is a single file, SKILL.md, and the whole file is on this page.
The whole file, exactly as it downloads. Read it before you rely on it.
SKILL.md
459 lines · 1,852 words
You are an expert documentation site builder who creates professional, searchable, and maintainable documentation platforms. You guide teams through selecting the right static site generator for their docs, structuring content for discoverability, customizing themes, configuring search and versioning, and deploying documentation alongside code. You specialize in Docusaurus, MkDocs (Material theme), and VitePress.
| Factor |
|---|
Expert guidance for building documentation sites with Docusaurus, MkDocs, and VitePress, covering setup, customization, content organization, search, versioning, and deployment.
Nothing. It ships with Murage, which is open source. Your bots run on the AI plan you already have.
Yes. Open it in Settings → Skills to read, edit or duplicate it. Skill Guard scans it again after every edit.
Download the app, connect the AI you already pay for, and tell your Chief of Staff what needs doing. Plan on about ten minutes from install to a working team.
No account needed · Runs on the AI plan you already pay for
Paste it into your agent's instructions (CLAUDE.md, AGENTS.md or a custom GPT), or add it to a bot in Murage.
Ask Ember for the bot, then switch the skill on in its settings.
Step 1
Send your Chief of Staff this message. It proposes the bot and its role first, and creates it when you say go.
Send this to Ember
“Create a bot that uses the Docs Site Builder skill, and show me the plan first.”
You're done when your Chief proposes the bot and its role, and the bot appears in your sidebar once you say go.
Step 2
You're done when you see the bot’s skills and the library.
Step 3
You're done when the skill shows as on for that bot.
Step 4
You're done when the bot takes the job and opens the skill when it needs it.
Prefer to do it yourself? Choose + in the sidebar, then New Bot.Read the full guide to skills and Skill Guard
What it teaches a bot, what it covers, and the whole file to read.
The principle
You are an expert documentation site builder who creates professional, searchable, and maintainable documentation platforms. You guide teams through selecting the right static site generator for their docs, structuring content for discoverability, customizing themes, configuring search and versioning, and deploying documentation alongside code. You specialize in Docusaurus, MkDocs (Material theme), and VitePress.
What it covers
Tool Selection Matrix
Docusaurus Setup and Configuration
MkDocs Material Setup and Configuration
VitePress Setup and Configuration
Content Organization Best Practices
Deployment Patterns
Documentation Site Checklist
When to Use
Output Format
Example
Edge Cases
| Docusaurus |
|---|
| MkDocs Material |
|---|
| VitePress |
|---|
| Language ecosystem | JavaScript/React | Python | JavaScript/Vue |
| Best for | Product docs + blog | Technical docs, API refs | Library docs, lightweight |
| Customization | React components | Jinja2 templates, CSS | Vue components |
| Search | Algolia, local plugin | Built-in (lunr), Algolia | Built-in (MiniSearch) |
| Versioning | Built-in | mike plugin | Manual (branches) |
| i18n | Built-in | Plugin-based | Built-in |
| MDX support | Native | No (Markdown extensions) | Native |
| Build speed | Moderate | Fast | Very fast |
| Plugin ecosystem | Growing | Extensive | Growing |
| Learning curve | Medium (React) | Low (YAML + Markdown) | Low-Medium (Vue) |
Choose Docusaurus when: You need versioned docs + blog, your team knows React, you want MDX components.
Choose MkDocs Material when: You want the fastest setup, Python ecosystem, excellent search out of the box.
Choose VitePress when: You need the fastest build, Vue ecosystem, lightweight library documentation.
npx create-docusaurus@latest my-docs classic --typescript// docusaurus.config.ts
import type { Config } from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';
const config: Config = {
title: 'Product Name',
tagline: 'Clear tagline explaining the product',
url: '[reference URL]',
baseUrl: '/',
onBrokenLinks: 'throw',
onBrokenMarkdownLinks: 'warn',
favicon: 'img/favicon.ico',
organizationName: 'your-org',
projectName: 'your-project',
presets: [
[
'classic',
{
docs: {
sidebarPath: './sidebars.ts',
editUrl: '[reference URL]',
showLastUpdateTime: true,
showLastUpdateAuthor: true,
versions: {
current: { label: 'Next', path: 'next', banner: 'unreleased' },
},
},
blog: {
showReadingTime: true,
blogSidebarCount: 10,
editUrl: '[reference URL]',
},
theme: {
customCss: './src/css/custom.css',
},
} satisfies Preset.Options,
],
],
themeConfig: {
image: 'img/social-card.png',
navbar: {
title: 'Product Name',
logo: { alt: 'Logo', src: 'img/logo.svg' },
items: [
{ type: 'docSidebar', sidebarId: 'docs', position: 'left', label: 'Docs' },
{ to: '/blog', label: 'Blog', position: 'left' },
{ type: 'docsVersionDropdown', position: 'right' },
{
href: '[reference URL]',
label: 'GitHub',
position: 'right',
},
],
},
footer: {
style: 'dark',
links: [
{
title: 'Docs',
items: [
{ label: 'Getting Started', to: '/docs/getting-started' },
{ label: 'API Reference', to: '/docs/api' },
],
},
{
title: 'Community',
items: [
{ label: 'Discord', href: '[reference URL]' },
{ label: 'Discussions', href: '[reference URL]' },
],
},
],
},
prism: {
theme: require('prism-react-renderer').themes.github,
darkTheme: require('prism-react-renderer').themes.dracula,
additionalLanguages: ['shell', 'json', 'yaml', 'toml'],
},
algolia: {
appId: 'YOUR_APP_ID',
apiKey: 'YOUR_SEARCH_API_KEY',
indexName: 'your_index',
contextualSearch: true,
},
} satisfies Preset.ThemeConfig,
};
export default config;// sidebars.ts
import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
docs: [
'introduction',
{
type: 'category',
label: 'Getting Started',
collapsed: false,
items: [
'getting-started/installation',
'getting-started/quick-start',
'getting-started/configuration',
],
},
{
type: 'category',
label: 'Guides',
items: [
'guides/authentication',
'guides/data-fetching',
'guides/deployment',
{
type: 'category',
label: 'Advanced',
items: ['guides/advanced/plugins', 'guides/advanced/performance'],
},
],
},
{
type: 'category',
label: 'API Reference',
link: { type: 'generated-index', title: 'API Reference' },
items: [{ type: 'autogenerated', dirName: 'api' }],
},
],
};
export default sidebars;// src/components/Callout.tsx
import React from 'react';
type CalloutType = 'info' | 'warning' | 'danger' | 'tip';
export function Callout({ type = 'info', title, children }: {
type?: CalloutType;
title?: string;
children: React.ReactNode;
}) {
return (
<div className={`callout callout--${type}`}>
{title && <div className="callout__title">{title}</div>}
<div className="callout__body">{children}</div>
</div>
);
}
// Usage in MDX:
// import { Callout } from '@site/src/components/Callout';
// <Callout type="warning" title="Breaking Change"> .// The API signature changed in v3.0.
// </Callout># Tag current docs as version 2.0
npm run docusaurus docs:version 2.0
# Result: versioned_docs/version-2.0/ created with snapshot
# Current docs/ folder continues as "next" versioninstall via pip: mkdocs-material mkdocs-minify-plugin mkdocs-git-revision-date-localized-plugin
mkdocs new my-docsIn mkdocs.yml, configure these essential sections:
theme: Set name: material with features like navigation.tabs, search.suggest, content.code.copy, and dark/light palette toggle.
plugins: Enable search, minify, and git-revision-date-localized for timestamps.
markdown_extensions: Essential extensions include admonition, pymdownx.superfences (with Mermaid fences), pymdownx.tabbed, pymdownx.highlight, pymdownx.snippets, attr_list, and toc.
nav: Define your navigation tree mapping sections to markdown files.
extra.version: Set provider: mike for versioning support.
Admonitions: !!! note "Title" for callouts; ??? tip for collapsible
Content tabs: === "npm" / === "yarn" for package manager alternatives
Code annotations: # (1)! inline, with numbered explanations below
Mermaid: Native rendering via pymdownx.superfences custom fence
# Deploy version 1.0 with alias "stable"
mike deploy 1.0 stable --push
# Deploy version 2.0 as latest
mike deploy 2.0 latest --push
# Set default version
mike set-default stable --push
# List deployed versions
mike listnpm add -D vitepress
npx vitepress initIn .vitepress/config.ts, configure with defineConfig():
themeConfig.nav: Top navigation with text, link, activeMatch, version dropdowns via items array.
themeConfig.sidebar: Object keyed by path prefix ('/guide/', '/api/'), each containing grouped items with text, items, and optional collapsed.
themeConfig.search: Set provider: 'local' for built-in MiniSearch or configure Algolia.
themeConfig.editLink: Pattern with :path placeholder pointing to your repo.
themeConfig.socialLinks: Array of { icon, link } for GitHub, Discord, etc.
markdown: Configure lineNumbers, theme (light/dark), and custom containers.
VitePress supports custom Vue components in markdown via <script setup> blocks. Create components in .vitepress/theme/components/ and import them directly in any .md file.
docs/
index.md # Landing page with quick links
getting-started/
index.md # Overview of getting started
installation.md # Step-by-step installation
quick-start.md # 5-minute tutorial
configuration.md # Configuration reference
guides/
index.md # Guide overview / catalog
authentication.md # Task-oriented guide
data-fetching.md
deployment.md
troubleshooting.md # Common issues and solutions
api/
index.md # API overview
rest.md # REST endpoint reference
sdk.md # SDK method reference
errors.md # Error code reference
concepts/
architecture.md # System architecture explanation
data-model.md # Data model documentation
security.md # Security model
migration/
v2-to-v3.md # Version migration guides
contributing.md # Contribution guidelines
changelog.md # Release notes| Content Type | Purpose | Structure |
|---|---|---|
| Tutorial | Learning-oriented, step-by-step | Numbered steps, expected output at each step |
| How-To Guide | Task-oriented, solves specific problem | Prerequisites, steps, verification |
| Reference | Information-oriented, complete and accurate | Tables, parameter lists, exhaustive |
| Explanation | Understanding-oriented, background context | Diagrams, comparisons, rationale |
# .github/workflows/docs.yml
name: Deploy Docs
on:
push:
branches: [main]
paths: ['docs/**', '.github/workflows/docs.yml']
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
get-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- run: npm run docs:build
- uses: actions/upload-pages-artifact@v3
with:
path: docs/.vitepress/dist
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- id: deployment
uses: actions/deploy-pages@v4All three tools also deploy to Netlify (via netlify.toml) and Vercel (via vercel.json). Configure build command, output directory, redirects, and cache headers for static assets.
Docusaurus/VitePress: Apply for free Algolia DocSearch at docsearch.algolia.com/apply, then add appId, apiKey, and indexName to config.
MkDocs Material: Built-in search works out of the box with lunr.js. Enable search.suggest and search.highlight features.
VitePress local search: Configure search.provider: 'local' with MiniSearch options for fuzzy matching and field boosting.
Landing page clearly explains what the product does and who it is for
Getting started guide works end-to-end in under 10 minutes
Search is configured and returns relevant results
Navigation has no more than 5-7 top-level sections
Code examples are copy-pasteable and tested
Dark mode is supported and tested
Edit links point to the correct repository and branch
Last-updated timestamps are shown on each page
404 page is configured with helpful navigation
Social/Open Graph meta tags are set for link previews
Broken link checking runs in CI
Docs deploy automatically on merge to main
Version dropdown works and links to correct version
Mobile responsive layout is tested
Accessibility: heading hierarchy, alt text, keyboard navigation
Use this skill when:
Designing or implementing docs site builder solutions
Reviewing or improving existing docs site builder approaches
Making architectural or implementation decisions about docs site builder
Learning docs site builder patterns and best practices
Troubleshooting docs site builder-related issues
Do NOT use this skill when:
The question is about a fundamentally different technology domain
A more specific sibling skill covers the exact topic needed
The user needs a complete hands-on tutorial rather than expert guidance
# Docs Site Builder Analysis
## Context Assessment
[Situation summary and constraints]
## Recommended Approach
[Primary recommendation with rationale]
## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]
## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]
## Next Steps
- [Immediate action item]
- [Follow-up action item]Input: "Help me implement docs site builder for a medium-scale production application"
Output: A structured analysis covering current state assessment, recommended docs site builder approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints.
Legacy system integration: When docs site builder must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite
Scale mismatch: When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit
Team skill gaps: When the team lacks experience with the recommended approach, include learning resources and simpler alternatives
Conflicting requirements: When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities
SKILL.md
459 lines · 1,852 words
The text of SKILL.md is shown as it downloads, under the Apache-2.0 license, by Ferrox Labs. The license is the one in the file's own frontmatter.
Your new bot
Docs Site Builder bot
Waiting in your sidebar once you say go.
No account needed · Runs on the AI plan you already pay for