Agent skill

docusaurus

Deep integration with Docusaurus for documentation site development. Configure projects, manage sidebars, versioning, i18n, develop plugins, and optimize builds for React-based documentation.

View SKILL.md on GitHub Repository
Stars 514
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/a5c-ai/babysitter/tree/main/library/specializations/technical-documentation/skills/docusaurus

Metadata

Additional technical details for this skill

author
babysitter-sdk
version
1.0.0

SKILL.md

Docusaurus Skill

Deep integration with Docusaurus for documentation site development.

Capabilities

  • Generate Docusaurus project configuration
  • Create and manage sidebar structures (sidebars.js)
  • Configure versioning and i18n
  • Develop custom Docusaurus plugins
  • MDX component creation and integration
  • Build optimization and debugging
  • Algolia DocSearch configuration
  • Theme customization

Usage

Invoke this skill when you need to:

  • Set up a new Docusaurus documentation site
  • Configure sidebars and navigation
  • Implement versioned documentation
  • Add internationalization (i18n)
  • Create custom plugins or themes

Inputs

Parameter Type Required Description
action string Yes init, configure, sidebar, version, i18n, plugin
projectPath string Yes Path to Docusaurus project
config object No Configuration options
version string No Version tag for versioning
locale string No Locale code for i18n

Input Example

json
{
  "action": "configure",
  "projectPath": "./docs-site",
  "config": {
    "title": "My Documentation",
    "tagline": "Developer documentation for My Product",
    "url": "https://docs.example.com",
    "organizationName": "my-org",
    "projectName": "my-project"
  }
}

Project Configuration

docusaurus.config.js

javascript
// @ts-check
const { themes } = require('prism-react-renderer');

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: 'My Documentation',
  tagline: 'Developer documentation for My Product',
  favicon: 'img/favicon.ico',

  url: 'https://docs.example.com',
  baseUrl: '/',

  organizationName: 'my-org',
  projectName: 'my-project',

  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',

  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'ja'],
  },

  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: './sidebars.js',
          editUrl: 'https://github.com/my-org/my-project/edit/main/',
          showLastUpdateTime: true,
          showLastUpdateAuthor: true,
          versions: {
            current: {
              label: 'Next',
              path: 'next',
            },
          },
        },
        blog: {
          showReadingTime: true,
          editUrl: 'https://github.com/my-org/my-project/edit/main/',
        },
        theme: {
          customCss: './src/css/custom.css',
        },
      }),
    ],
  ],

  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      image: 'img/social-card.jpg',
      navbar: {
        title: 'My Project',
        logo: {
          alt: 'My Project Logo',
          src: 'img/logo.svg',
        },
        items: [
          {
            type: 'docSidebar',
            sidebarId: 'tutorialSidebar',
            position: 'left',
            label: 'Docs',
          },
          {
            type: 'docsVersionDropdown',
            position: 'right',
          },
          {
            type: 'localeDropdown',
            position: 'right',
          },
          {
            href: 'https://github.com/my-org/my-project',
            label: 'GitHub',
            position: 'right',
          },
        ],
      },
      footer: {
        style: 'dark',
        links: [
          {
            title: 'Docs',
            items: [
              { label: 'Getting Started', to: '/docs/intro' },
              { label: 'API Reference', to: '/docs/api' },
            ],
          },
          {
            title: 'Community',
            items: [
              { label: 'Discord', href: 'https://discord.gg/example' },
              { label: 'Twitter', href: 'https://twitter.com/example' },
            ],
          },
        ],
        copyright: `Copyright ${new Date().getFullYear()} My Project.`,
      },
      prism: {
        theme: themes.github,
        darkTheme: themes.dracula,
        additionalLanguages: ['bash', 'json', 'yaml'],
      },
      algolia: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_SEARCH_API_KEY',
        indexName: 'my-project',
        contextualSearch: true,
      },
    }),
};

module.exports = config;

Sidebar Configuration

sidebars.js

javascript
/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
  tutorialSidebar: [
    'intro',
    {
      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/api-usage',
        {
          type: 'category',
          label: 'Advanced',
          items: [
            'guides/advanced/caching',
            'guides/advanced/performance',
          ],
        },
      ],
    },
    {
      type: 'category',
      label: 'API Reference',
      link: {
        type: 'generated-index',
        title: 'API Reference',
        description: 'Complete API documentation',
      },
      items: [
        'api/client',
        'api/authentication',
        'api/resources',
      ],
    },
    {
      type: 'link',
      label: 'GitHub',
      href: 'https://github.com/my-org/my-project',
    },
  ],
};

module.exports = sidebars;

Custom Components

Tabs Component

jsx
// src/components/CodeTabs.jsx
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import CodeBlock from '@theme/CodeBlock';

export function CodeTabs({ children, labels = ['JavaScript', 'Python', 'cURL'] }) {
  return (
    <Tabs groupId="code-examples">
      {labels.map((label, index) => (
        <TabItem key={label} value={label.toLowerCase()} label={label}>
          <CodeBlock language={label.toLowerCase()}>
            {children[index]}
          </CodeBlock>
        </TabItem>
      ))}
    </Tabs>
  );
}

API Endpoint Component

jsx
// src/components/ApiEndpoint.jsx
import React from 'react';
import styles from './ApiEndpoint.module.css';

export function ApiEndpoint({ method, path, description }) {
  const methodColors = {
    GET: '#61affe',
    POST: '#49cc90',
    PUT: '#fca130',
    DELETE: '#f93e3e',
    PATCH: '#50e3c2',
  };

  return (
    <div className={styles.endpoint}>
      <span
        className={styles.method}
        style={{ backgroundColor: methodColors[method] }}
      >
        {method}
      </span>
      <code className={styles.path}>{path}</code>
      <p className={styles.description}>{description}</p>
    </div>
  );
}

Versioning

Creating a Version

bash
# Create version snapshot
npm run docusaurus docs:version 1.0.0

# Project structure after versioning
docs/
├── intro.md              # Current (next) version
├── getting-started/
versioned_docs/
├── version-1.0.0/
│   ├── intro.md
│   └── getting-started/
versioned_sidebars/
├── version-1.0.0-sidebars.json
versions.json

versions.json

json
[
  "2.0.0",
  "1.1.0",
  "1.0.0"
]

Internationalization (i18n)

Translation Structure

i18n/
├── en/
│   └── docusaurus-plugin-content-docs/
│       └── current/
│           └── intro.md
├── es/
│   └── docusaurus-plugin-content-docs/
│       └── current/
│           └── intro.md
└── ja/
    └── docusaurus-plugin-content-docs/
        └── current/
            └── intro.md

Write Translations Command

bash
# Generate translation files
npm run write-translations -- --locale es

# Start dev server for locale
npm run start -- --locale es

Custom Plugin

Plugin Template

javascript
// plugins/my-plugin/index.js
module.exports = function myPlugin(context, options) {
  return {
    name: 'my-plugin',

    async loadContent() {
      // Load custom content
      return { /* content */ };
    },

    async contentLoaded({ content, actions }) {
      const { addRoute, createData } = actions;

      // Create custom routes
      addRoute({
        path: '/my-custom-page',
        component: '@site/src/pages/MyPage.jsx',
        exact: true,
      });
    },

    configureWebpack(config, isServer, utils) {
      // Modify webpack config
      return {
        resolve: {
          alias: {
            '@custom': path.resolve(__dirname, 'src'),
          },
        },
      };
    },
  };
};

Algolia DocSearch

algolia.config.json

json
{
  "index_name": "my-project",
  "start_urls": [
    "https://docs.example.com/"
  ],
  "sitemap_urls": [
    "https://docs.example.com/sitemap.xml"
  ],
  "selectors": {
    "lvl0": ".menu__link--active",
    "lvl1": "article h1",
    "lvl2": "article h2",
    "lvl3": "article h3",
    "lvl4": "article h4",
    "content": "article p, article li"
  }
}

Workflow

  1. Initialize project - Create new Docusaurus site
  2. Configure - Set up docusaurus.config.js
  3. Structure content - Organize docs and sidebars
  4. Add components - Create custom MDX components
  5. Configure search - Set up Algolia DocSearch
  6. Add versioning - Create version snapshots
  7. Deploy - Build and deploy to hosting

Dependencies

json
{
  "dependencies": {
    "@docusaurus/core": "^3.0.0",
    "@docusaurus/preset-classic": "^3.0.0",
    "@mdx-js/react": "^3.0.0",
    "prism-react-renderer": "^2.0.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}

CLI Commands

bash
# Create new project
npx create-docusaurus@latest my-docs classic

# Start development server
npm run start

# Build for production
npm run build

# Create version
npm run docusaurus docs:version 1.0.0

# Generate translations
npm run write-translations -- --locale es

# Deploy to GitHub Pages
npm run deploy

Best Practices Applied

  • Use MDX for interactive components
  • Implement versioning for stable releases
  • Configure search for discoverability
  • Add edit links for community contributions
  • Use admonitions for callouts
  • Optimize images with ideal-image
  • Enable last updated timestamps

References

Target Processes

  • docs-as-code-pipeline.js
  • docs-versioning.js
  • interactive-tutorials.js
  • knowledge-base-setup.js

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

a5c-ai/babysitter

gsd-tools

Central utility skill for GSD operations. Provides config parsing, slug generation, timestamps, path operations, and orchestrates calls to other specialized skills. Acts as the unified entry point that the original gsd-tools.cjs provided via its lib/ modules (commands, config, core, init).

514 31
Explore
a5c-ai/babysitter

model-profile-resolution

Resolve model profile (quality/balanced/budget) at orchestration start and map agents to specific models. Enables cost/quality tradeoffs by selecting appropriate AI models for each agent role.

514 31
Explore
a5c-ai/babysitter

verification-suite

Plan structure validation, phase completeness checks, reference integrity verification, and artifact existence confirmation. Provides the structured verification layer ensuring GSD artifacts are well-formed and complete.

514 31
Explore
a5c-ai/babysitter

state-management

STATE.md reading, writing, and field-level updates. Provides cross-session state persistence via .planning/STATE.md with structured fields for current task, completed phases, blockers, decisions, and quick tasks.

514 31
Explore
a5c-ai/babysitter

git-integration

Git commit patterns, formats, and conventions for GSD methodology. Provides atomic commits per task, structured commit messages, planning file commits, branch management, and milestone tag operations.

514 31
Explore
a5c-ai/babysitter

frontmatter-parsing

YAML frontmatter parsing and manipulation for .planning/ documents. Provides read, write, update, query, and validation operations on frontmatter blocks in GSD markdown artifacts.

514 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results