Documentation Site Expert

Documentation Site Expert (2026 Edition)

English | Bahasa Indonesia

English

Orchestration & Integration

• modern-web-guidance: HTML5/CSS standards, modern browser APIs, and accessibility guidelines.
• design-system-architect: Component documentation, design token references, and Storybook integration.
• ui-ux-pro-max: Documentation typography hierarchy, syntax themes, and search UX.
• visual-ui-auditor: Multimodal vision auditing of component documentation previews and Storybook.
• anti-slop: Anti-slop technical documentation, zero marketing buzzwords, concrete code samples.
• openapi-swagger-codegen-expert: Auto-generate API reference pages from OpenAPI 3.1 specs.
• astro-framework-expert: Astro Starlight as a full-featured docs site platform.
• seo: Documentation SEO — canonical URLs, sitemap.xml, structured data, and GEO.
• ci-cd-devops-architect: Automated deployment pipelines to Vercel, Cloudflare Pages, GitHub Pages.
• senior-frontend: Custom MDX components, interactive playgrounds, and React-based doc UIs.
• search-engine-expert: Algolia DocSearch, Pagefind, and Typesense integration for doc search.
• global-a11y-i18n-expert: i18n multi-language documentation and WCAG-compliant doc sites.

Description

Expert guide for building production-grade technical documentation sites and component libraries. Covers Mintlify (AI-native SaaS docs), Docusaurus 3 (React/OSS), Storybook 8 (component playground), VitePress 2 (Vue-powered), and Astro Starlight (content-heavy i18n). Includes API reference generation, versioning strategies, search integration, Chromatic visual testing, and CI/CD deployment workflows.

Trigger Conditions

• Creating documentation sites for APIs, libraries, or SaaS products.
• Setting up Storybook for component documentation and visual regression.
• Choosing a documentation framework for an open-source project.
• Generating API reference docs from OpenAPI specs.
• Migrating from legacy docs (GitBook, Confluence, readme.io) to modern static sites.
• Adding versioning, search, or i18n to an existing documentation site.

Framework Selection Matrix

Decision Rule:

• SaaS product → Mintlify (zero-config, AI search, API playground)
• OSS library → Docusaurus (versioning + Algolia + community plugins)
• Component library → Storybook (visual testing + interactions + Chromatic)
• Vue project → VitePress (native Vue integration, blazing fast)
• Content-heavy / i18n-first → Astro Starlight (Pagefind, i18n routing)

1. Mintlify

mint.json — Complete Configuration

jsonCopy code
{
  "name": "Acme API",
  "logo": {
    "light": "/logo/light.svg",
    "dark": "/logo/dark.svg"
  },
  "favicon": "/favicon.svg",
  "colors": {
    "primary": "#0D9373",
    "light": "#07C983",
    "dark": "#0D9373",
    "anchors": { "from": "#0D9373", "to": "#07C983" }
  },
  "topbarLinks": [
    { "name": "Support", "url": "mailto:support@acme.com" }
  ],
  "topbarCtaButton": {
    "name": "Dashboard",
    "url": "https://app.acme.com"
  },
  "tabs": [
    { "name": "API Reference", "url": "api-reference" }
  ],
  "anchors": [
    { "name": "Changelog", "icon": "list", "url": "changelog" },
    { "name": "GitHub", "icon": "github", "url": "https://github.com/acme/api" }
  ],
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["introduction", "quickstart", "authentication"]
    },
    {
      "group": "Guides",
      "pages": ["guides/webhooks", "guides/pagination", "guides/rate-limits"]
    },
    {
      "group": "API Reference",
      "pages": ["api-reference/introduction", "api-reference/endpoints/users", "api-reference/endpoints/payments"]
    }
  ],
  "openapi": "https://api.acme.com/openapi.json",
  "api": {
    "baseUrl": "https://api.acme.com/v1",
    "auth": {
      "method": "bearer"
    },
    "playground": { "mode": "show" }
  },
  "feedback": { "thumbsRating": true, "suggestEdit": true },
  "search": { "prompt": "Search Acme docs..." },
  "footerSocials": {
    "twitter": "https://twitter.com/acme",
    "github": "https://github.com/acme"
  }
}

MDX Authoring with Custom Components

mdxCopy code
---
title: "Authentication"
description: "Secure your API requests with Bearer tokens."
---

import { Note, Warning, CodeGroup } from 'mintlify/components';

<Note>
  All API requests require an `Authorization: Bearer <token>` header.
</Note>

<Warning>
  Never expose your API secret in client-side code or version control.
</Warning>

## Obtaining an API Key

Navigate to **Settings → API Keys** in your dashboard and click **Create Key**.

<CodeGroup>
```bash cURL
curl https://api.acme.com/v1/users \
  -H "Authorization: Bearer $ACME_API_KEY"

typescriptCopy code
import AcmeClient from '@acme/sdk';

const client = new AcmeClient({ apiKey: process.env.ACME_API_KEY });
const users = await client.users.list();

API Playground Auto-Generation from OpenAPI

bashCopy code
# Mintlify CLI — scrape OpenAPI and generate MDX stubs
npm install -g mintlify
mintlify dev             # local preview at http://localhost:3000
mintlify scrape          # auto-generate pages from openapi field in mint.json

Mintlify reads the "openapi" field in mint.json and auto-generates interactive API reference pages with a live request playground, response schema viewer, and try-it UI — zero additional MDX authoring required.

2. Docusaurus 3

docusaurus.config.ts — Production-Ready Example

typescriptCopy code
import type { Config } from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';

const config: Config = {
  title: 'Acme Docs',
  tagline: 'The fastest way to build on Acme',
  favicon: 'img/favicon.ico',
  url: 'https://docs.acme.com',
  baseUrl: '/',
  organizationName: 'acme',
  projectName: 'acme-docs',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'id', 'ja'],
  },
  presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: './sidebars.ts',
          editUrl: 'https://github.com/acme/docs/tree/main/',
          showLastUpdateTime: true,
          showLastUpdateAuthor: true,
          versions: {
            current: { label: 'v3 (Next)', path: 'next', banner: 'unreleased' },
          },
          lastVersion: 'v2',
        },
        blog: {
          showReadingTime: true,
          feedOptions: { type: ['rss', 'atom'], xslt: true },
        },
        theme: {
          customCss: './src/css/custom.css',
        },
        sitemap: { changefreq: 'weekly', priority: 0.5 },
      } satisfies Preset.Options,
    ],
  ],
  plugins: [
    [
      'docusaurus-plugin-openapi-docs',
      {
        id: 'api',
        docsPluginId: 'classic',
        config: {
          acme: {
            specPath: 'openapi/acme.yaml',
            outputDir: 'docs/api',
            sidebarOptions: { groupPathsBy: 'tag', categoryLinkSource: 'tag' },
          },
        },
      },
    ],
    ['@docusaurus/plugin-ideal-image', { max: 1030, min: 640, steps: 2 }],
  ],
  themeConfig: {
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'acme_docs',
      contextualSearch: true,
      searchPagePath: 'search',
    },
    prism: {
      theme: { plain: {}, styles: [] },
      additionalLanguages: ['bash', 'json', 'yaml', 'typescript'],
    },
    navbar: {
      title: 'Acme',
      logo: { alt: 'Acme Logo', src: 'img/logo.svg' },
      items: [
        { type: 'docsVersionDropdown', position: 'left' },
        { type: 'localeDropdown', position: 'right' },
        { href: 'https://github.com/acme/docs', label: 'GitHub', position: 'right' },
      ],
    },
    footer: {
      style: 'dark',
      links: [
        { title: 'Docs', items: [{ label: 'Getting Started', to: '/docs/intro' }] },
        { title: 'Community', items: [{ label: 'Discord', href: 'https://discord.gg/acme' }] },
      ],
      copyright: `Copyright © ${new Date().getFullYear()} Acme, Inc.`,
    },
  } satisfies Preset.ThemeConfig,
};

export default config;

Versioning Strategy

bashCopy code
# Create a new versioned snapshot (freezes current /docs)
npm run docusaurus docs:version 2.0.0

# Resulting structure:
# versioned_docs/version-2.0.0/   ← frozen snapshot
# versioned_sidebars/version-2.0.0-sidebars.json
# versions.json                   ← ["2.0.0"]
# docs/                           ← "next" (unreleased)

Algolia DocSearch Integration

bashCopy code
# Request free DocSearch tier at: https://docsearch.algolia.com/apply
# Then install crawler config:
npm install @algolia/client-search

javascriptCopy code
// algolia-crawler-config.js (submitted to Algolia dashboard)
new Crawler({
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_WRITE_API_KEY',
  rateLimit: 8,
  startUrls: ['https://docs.acme.com/'],
  renderJavaScript: false,
  sitemaps: ['https://docs.acme.com/sitemap.xml'],
  ignoreCanonicalTo: true,
  discoveryPatterns: ['https://docs.acme.com/**'],
  actions: [{
    indexName: 'acme_docs',
    pathsToMatch: ['https://docs.acme.com/**'],
    recordExtractor: ({ $, helpers }) => {
      return helpers.docsearch({
        recordProps: {
          lvl1: ['header h1', 'article h1', 'main h1'],
          content: ['article p, article li', 'main p, main li'],
        },
        indexHeadings: true,
      });
    },
  }],
  initialIndexSettings: {
    acme_docs: {
      attributesForFaceting: ['type', 'lang', 'version'],
      attributesToRetrieve: ['hierarchy', 'content', 'anchor', 'url'],
      attributesToHighlight: ['hierarchy', 'content'],
      attributesToSnippet: ['content:10'],
      searchableAttributes: ['unordered(hierarchy.lvl0)', 'content'],
      distinct: true,
      attributeForDistinct: 'url',
      ranking: ['words', 'filters', 'typo', 'attribute', 'proximity', 'exact', 'custom'],
    },
  },
});

MDX Plugins

bashCopy code
npm install remark-math rehype-katex remark-gfm rehype-mermaid

typescriptCopy code
// docusaurus.config.ts — add to docs preset options:
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

// inside docs preset:
remarkPlugins: [remarkMath],
rehypePlugins: [rehypeKatex],

3. Storybook 8

Installation & Autodocs

bashCopy code
# Initialize Storybook in an existing project
npx storybook@latest init

# Start dev server
npm run storybook

# Build static site
npm run build-storybook

Story with Interaction Testing

typescriptCopy code
// src/components/Button/Button.stories.ts
import type { Meta, StoryObj } from '@storybook/react';
import { expect, userEvent, within } from '@storybook/test';
import { Button } from './Button';

const meta = {
  title: 'UI/Button',
  component: Button,
  tags: ['autodocs'],
  argTypes: {
    variant: { control: 'select', options: ['primary', 'secondary', 'ghost'] },
    size: { control: 'radio', options: ['sm', 'md', 'lg'] },
    disabled: { control: 'boolean' },
  },
} satisfies Meta<typeof Button>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  args: { variant: 'primary', size: 'md', children: 'Click me' },
};

export const InteractionTest: Story = {
  args: { variant: 'primary', children: 'Submit' },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    const button = canvas.getByRole('button', { name: /submit/i });
    await userEvent.click(button);
    await expect(button).toBeInTheDocument();
  },
};

.storybook/main.ts — Addon Ecosystem

typescriptCopy code
import type { StorybookConfig } from '@storybook/nextjs';

const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    '@storybook/addon-onboarding',
    '@storybook/addon-links',
    '@storybook/addon-essentials',      // Controls, Docs, Actions, Viewport, Backgrounds
    '@storybook/addon-interactions',    // play() function testing
    '@storybook/addon-a11y',            // Axe-core accessibility audit
    '@chromatic-com/storybook',         // Chromatic visual testing
    '@storybook/addon-themes',          // Light/Dark theme switching
  ],
  framework: {
    name: '@storybook/nextjs',
    options: {},
  },
  docs: { autodocs: 'tag' },
  staticDirs: ['../public'],
};

export default config;

Chromatic Visual Testing

bashCopy code
npm install --save-dev chromatic

# Run visual regression against baseline
npx chromatic --project-token=<your-token>

# CI flag — accept changes automatically on main branch
npx chromatic --project-token=<your-token> --auto-accept-changes main

yamlCopy code
# .github/workflows/chromatic.yml
name: Chromatic
on: push
jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-node@v4
        with: { node-version: 22, cache: 'npm' }
      - run: npm ci
      - name: Run Chromatic
        uses: chromaui/action@v11
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          exitZeroOnChanges: true

4. VitePress 2

docs/.vitepress/config.mts

typescriptCopy code
import { defineConfig } from 'vitepress';

export default defineConfig({
  lang: 'en-US',
  title: 'Acme Library',
  description: 'A powerful TypeScript utility library.',
  lastUpdated: true,
  cleanUrls: true,
  srcDir: './src',
  outDir: '../dist-docs',

  head: [
    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/logo.svg' }],
    ['meta', { name: 'theme-color', content: '#5f67ee' }],
    ['meta', { property: 'og:type', content: 'website' }],
  ],

  themeConfig: {
    logo: '/logo.svg',
    nav: [
      { text: 'Guide', link: '/guide/what-is-acme' },
      { text: 'Reference', link: '/reference/config' },
      {
        text: 'v2.0',
        items: [
          { text: 'v1.x Docs', link: 'https://v1.acme.dev' },
          { text: 'Changelog', link: '/changelog' },
        ],
      },
    ],
    sidebar: {
      '/guide/': [
        { text: 'Introduction', items: [
          { text: 'What is Acme?', link: '/guide/what-is-acme' },
          { text: 'Getting Started', link: '/guide/getting-started' },
        ]},
        { text: 'Advanced', items: [
          { text: 'Configuration', link: '/guide/configuration' },
          { text: 'Plugin API', link: '/guide/plugin-api' },
        ]},
      ],
    },
    editLink: {
      pattern: 'https://github.com/acme/lib/edit/main/docs/src/:path',
      text: 'Edit this page on GitHub',
    },
    search: { provider: 'local' },
    socialLinks: [{ icon: 'github', link: 'https://github.com/acme/lib' }],
  },

  locales: {
    root: { label: 'English', lang: 'en' },
    id: { label: 'Bahasa Indonesia', lang: 'id', link: '/id/', themeConfig: {
      nav: [{ text: 'Panduan', link: '/id/guide/what-is-acme' }],
    }},
  },
});

Vue 3 Custom Theme Component

vueCopy code
<!-- docs/.vitepress/theme/components/ApiPreview.vue -->
<script setup lang="ts">
import { ref } from 'vue';

const props = defineProps<{ endpoint: string; method?: 'GET' | 'POST' }>();
const response = ref<string | null>(null);

async function runRequest() {
  const res = await fetch(props.endpoint, { method: props.method ?? 'GET' });
  response.value = JSON.stringify(await res.json(), null, 2);
}
</script>

<template>
  <div class="api-preview">
    <div class="controls">
      <span class="method">{{ method ?? 'GET' }}</span>
      <code class="endpoint">{{ endpoint }}</code>
      <button @click="runRequest">Run</button>
    </div>
    <pre v-if="response" class="response">{{ response }}</pre>
  </div>
</template>

typescriptCopy code
// docs/.vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme';
import ApiPreview from './components/ApiPreview.vue';
import type { Theme } from 'vitepress';

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    app.component('ApiPreview', ApiPreview);
  },
} satisfies Theme;

5. Astro Starlight

Installation & Sidebar Config

bashCopy code
npm create astro@latest -- --template starlight

typescriptCopy code
// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'Acme Docs',
      logo: { src: './src/assets/logo.svg' },
      social: { github: 'https://github.com/acme/acme' },
      defaultLocale: 'root',
      locales: {
        root: { label: 'English', lang: 'en' },
        id: { label: 'Bahasa Indonesia', lang: 'id' },
        ja: { label: '日本語', lang: 'ja' },
      },
      sidebar: [
        { label: 'Start Here', items: [
          { label: 'Introduction', link: '/intro/' },
          { label: 'Installation', link: '/install/' },
        ]},
        { label: 'Guides', autogenerate: { directory: 'guides' } },
        { label: 'Reference', autogenerate: { directory: 'reference' } },
      ],
      editLink: { baseUrl: 'https://github.com/acme/docs/edit/main/' },
      lastUpdated: true,
      pagination: true,
      tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 4 },
      customCss: ['./src/styles/custom.css'],
      components: {
        SiteTitle: './src/components/CustomSiteTitle.astro',
      },
    }),
  ],
});

Pagefind Search Configuration

Starlight ships with Pagefind out of the box — zero config needed. Pagefind runs at build time and creates a client-side search index from your HTML output.

bashCopy code
# Build triggers Pagefind indexing automatically
npm run build

# Pagefind index output: dist/pagefind/
# Bundle size: ~8 KB JS + compressed index shards

i18n MDX Page Structure

Copy code
src/content/docs/
├── intro.mdx              ← English (root locale)
├── install.mdx
├── guides/
│   └── quickstart.mdx
└── id/                    ← Bahasa Indonesia
    ├── intro.mdx
    ├── install.mdx
    └── guides/
        └── quickstart.mdx

mdxCopy code
---
# src/content/docs/id/intro.mdx
title: Pengantar
description: Selamat datang di dokumentasi Acme.
---

Acme adalah library TypeScript berkinerja tinggi untuk membangun pipeline data modern.

## Fitur Utama

- ⚡ **Performa tinggi** — dioptimalkan untuk throughput jutaan record per detik
- 🔒 **Type-safe** — dibangun dengan TypeScript strict mode
- 🧩 **Modular** — gunakan hanya modul yang Anda butuhkan

6. Content Architecture Best Practices

Versioning Strategy

Changelog Automation with Changesets

bashCopy code
npm install --save-dev @changesets/cli @changesets/changelog-github
npx changeset init

# Add a changeset (run after each PR)
npx changeset add

# Release: bump versions + update CHANGELOG.md
npx changeset version
npx changeset publish

jsonCopy code
// .changeset/config.json
{
  "$schema": "https://unpkg.com/@changesets/config/schema.json",
  "changelog": ["@changesets/changelog-github", { "repo": "acme/lib" }],
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

API Reference via openapi-typescript

bashCopy code
npm install --save-dev openapi-typescript typescript

# Generate types from live spec or local file
npx openapi-typescript https://api.acme.com/openapi.json -o src/types/api.d.ts
npx openapi-typescript ./openapi/acme.yaml -o src/types/api.d.ts

typescriptCopy code
// src/lib/api-client.ts — type-safe API client from generated types
import createClient from 'openapi-fetch';
import type { paths } from '../types/api';

export const apiClient = createClient<paths>({
  baseUrl: 'https://api.acme.com/v1',
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});

// Fully typed request — IDE autocomplete for paths, params, and response
const { data, error } = await apiClient.GET('/users/{id}', {
  params: { path: { id: '123' } },
});

7. Deployment

Vercel (Recommended for Mintlify + Docusaurus + VitePress)

jsonCopy code
// vercel.json — Docusaurus / VitePress
{
  "buildCommand": "npm run build",
  "outputDirectory": "build",
  "framework": null,
  "rewrites": [{ "source": "/(.*)", "destination": "/$1" }],
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
      ]
    }
  ]
}

Cloudflare Pages

yamlCopy code
# Build settings (Cloudflare Dashboard → Pages → Build & deployments)
# Build command:  npm run build
# Output dir:     build        (Docusaurus) | dist (VitePress/Starlight)
# Node.js:        22.x

tomlCopy code
# wrangler.toml — for Workers + Pages hybrid
name = "acme-docs"
compatibility_date = "2026-01-01"

[site]
bucket = "./build"

GitHub Pages Workflow

yamlCopy code
# .github/workflows/deploy-docs.yml
name: Deploy Docs
on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-node@v4
        with: { node-version: 22, cache: 'npm' }
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-pages-artifact@v3
        with: { path: build }

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment

Orchestration & Integration

• modern-web-guidance — HTML5/CSS standards, accessibility, and modern web platform APIs
• design-system-architect — design token docs, Storybook integration
• ui-ux-pro-max — documentation typography hierarchy, syntax themes, and search UX
• visual-ui-auditor — vision auditing of component documentation previews and Storybook
• anti-slop — technical documentation anti-slop, zero marketing buzzwords, concrete code samples
• openapi-swagger-codegen-expert — API reference auto-generation
• astro-framework-expert — Starlight configuration
• seo — sitemap, canonical, structured data
• ci-cd-devops-architect — automated deployment pipelines
• global-a11y-i18n-expert — multi-language documentation
• search-engine-expert — Algolia, Pagefind, Typesense

Sovereign Execution, Token Efficiency & Invariants

Bahasa Indonesia

Integrasi Orkestrasi

• modern-web-guidance: Standar HTML5/CSS, API browser modern, dan pedoman aksesibilitas.
• design-system-architect: Dokumentasi komponen dan referensi design token dengan Storybook.
• ui-ux-pro-max: Hierarki tipografi dokumentasi, tema sintaksis, dan UX pencarian.
• visual-ui-auditor: Audit visual multimodal untuk preview komponen dokumentasi dan Storybook.
• anti-slop: Dokumentasi teknis anti-slop, bebas buzzword pemasaran, contoh kode konkret.
• openapi-swagger-codegen-expert: Otomatisasi halaman referensi API dari spesifikasi OpenAPI 3.1.
• astro-framework-expert: Astro Starlight sebagai platform situs dokumentasi lengkap.
• seo: SEO dokumentasi — canonical URL, sitemap.xml, structured data, dan GEO.
• ci-cd-devops-architect: Pipeline deployment otomatis ke Vercel, Cloudflare Pages, GitHub Pages.
• senior-frontend: Komponen MDX kustom, playground interaktif, dan UI dokumentasi berbasis React.
• global-a11y-i18n-expert: Dokumentasi multi-bahasa i18n dan situs dokumentasi sesuai WCAG.

Deskripsi

Panduan ahli untuk membangun situs dokumentasi teknis tingkat produksi dan library komponen. Mencakup Mintlify (docs SaaS AI-native), Docusaurus 3 (React/OSS), Storybook 8 (playground komponen), VitePress 2 (berbasis Vue), dan Astro Starlight (konten berat dengan i18n). Termasuk panduan generasi referensi API, strategi versioning, integrasi pencarian, pengujian visual Chromatic, dan workflow CI/CD deployment.

Kondisi Pemicu

• Membuat situs dokumentasi untuk API, library, atau produk SaaS.
• Menyiapkan Storybook untuk dokumentasi komponen dan regresi visual.
• Memilih framework dokumentasi untuk proyek open-source.
• Menghasilkan halaman referensi API dari spesifikasi OpenAPI.
• Migrasi dari dokumentasi lama (GitBook, Confluence) ke situs statis modern.
• Menambahkan versioning, pencarian, atau i18n ke situs dokumentasi yang sudah ada.

Matriks Pemilihan Framework

Aturan Keputusan:

• Produk SaaS → Mintlify (zero-config, pencarian AI, playground API)
• Library OSS → Docusaurus (versioning + Algolia + plugin komunitas)
• Library komponen → Storybook (visual testing + interaksi + Chromatic)
• Proyek Vue → VitePress (integrasi Vue native, sangat cepat)
• Konten berat / i18n-first → Astro Starlight (Pagefind, routing i18n)

1. Mintlify — Ringkasan Konfigurasi

File mint.json mengontrol seluruh navigasi, branding, dan integrasi API playground. Field "openapi" menunjuk ke spesifikasi OpenAPI dan secara otomatis menghasilkan halaman referensi interaktif — tidak perlu authoring MDX tambahan untuk setiap endpoint.

bashCopy code
npm install -g mintlify
mintlify dev        # pratinjau lokal di http://localhost:3000
mintlify scrape     # hasilkan halaman dari field openapi di mint.json

Komponen MDX bawaan: <Note>, <Warning>, <Tip>, <Info>, <CodeGroup>, <Accordion>, <Card>, <CardGroup>, <Steps>, <Tabs> — langsung digunakan dalam file .mdx tanpa import.

2. Docusaurus 3 — Ringkasan

Docusaurus adalah pilihan terbaik untuk proyek open-source karena mendukung:

• Versioning: npm run docusaurus docs:version 2.0.0 membuat snapshot beku dari /docs saat ini.
• Algolia DocSearch: Gratis untuk proyek OSS — daftar di https://docsearch.algolia.com/apply.
• Plugin MDX: remark-math + rehype-katex untuk LaTeX, rehype-mermaid untuk diagram.
• Plugin OpenAPI: docusaurus-plugin-openapi-docs menghasilkan halaman referensi dari spec YAML.

3. Storybook 8 — Ringkasan

Storybook adalah standar industri untuk mendokumentasikan dan menguji komponen UI secara visual.

Fitur Utama:

• Autodocs: Tambahkan tags: ['autodocs'] ke meta story — halaman dokumentasi otomatis dihasilkan dari props TypeScript.
• Interaction Testing: Gunakan play() dengan @storybook/test untuk mensimulasikan interaksi pengguna dan memverifikasi perilaku komponen.
• Chromatic: Layanan visual regression testing — tangkap perubahan UI yang tidak disengaja di setiap PR.
• Addon Aksesibilitas: @storybook/addon-a11y menjalankan audit axe-core pada setiap story.

4. VitePress 2 — Ringkasan

VitePress adalah pilihan ideal untuk ekosistem Vue atau proyek library TypeScript yang membutuhkan dokumentasi cepat.

• File konfigurasi: docs/.vitepress/config.mts (TypeScript penuh)
• Pencarian lokal bawaan — tidak perlu Algolia untuk proyek kecil/menengah
• Integrasi komponen Vue langsung dalam halaman Markdown
• Dukungan i18n multi-bahasa melalui konfigurasi locales

5. Astro Starlight — Ringkasan

Starlight dibangun di atas Astro dan merupakan pilihan terbaik untuk dokumentasi konten berat dengan i18n.

• Pagefind: Pencarian statis client-side — dihasilkan saat build, ukuran bundle ~8KB JS.
• i18n: Dukung banyak bahasa dengan routing otomatis (/id/, /ja/, dll.)
• Sidebar otomatis: autogenerate: { directory: 'guides' } membuat sidebar dari struktur folder.
• Edit di GitHub: Link "Edit halaman ini" otomatis dihasilkan dari konfigurasi editLink.

6. Arsitektur Konten — Praktik Terbaik

Strategi Versioning:

• Gunakan docusaurus docs:version untuk snapshot rilis beku.
• Gunakan Changesets (@changesets/cli) untuk otomatisasi changelog dan bumping versi package.
• Sertakan badge versi semver di halaman utama docs.

Otomatisasi Changelog:

bashCopy code
npx changeset add       # tambahkan changeset setelah setiap PR
npx changeset version   # bump versi + update CHANGELOG.md
npx changeset publish   # publish ke npm

Referensi API via openapi-typescript:

bashCopy code
npx openapi-typescript https://api.acme.com/openapi.json -o src/types/api.d.ts

Hasilkan tipe TypeScript penuh dari spesifikasi OpenAPI — gunakan bersama openapi-fetch untuk client API yang fully type-safe.

7. Deployment

Mintlify di-deploy melalui platform Mintlify sendiri — hubungkan repo GitHub di dashboard mintlify.com dan setiap push ke main otomatis men-deploy.

Matriks Eksekusi Berdaulat, Efisiensi Token & Invarian