OpenParable
Skip to content
← Back to skills

A5c AI Docusaurus

Development
a5c-ai-docusaurus

A5c AI Docusaurus is an Agent Skill for development published in the farm-fe/farm repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/farm-fe/farm/blob/HEAD/.claude/skills/a5c-ai-docusaurus/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/a5c-ai-docusaurus, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

ParameterTypeRequiredDescription
actionstringYesinit, configure, sidebar, version, i18n, plugin
projectPathstringYesPath to Docusaurus project
configobjectNoConfiguration options
versionstringNoVersion tag for versioning
localestringNoLocale code for i18n

Input Example

{
  "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

// @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

/** @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

// 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

// 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

# 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

[
  "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

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

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

Custom Plugin

Plugin Template

// 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

{
  "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

{
  "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

# 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