DocsSite Specialization

The DocsSite type is optimized for technical documentation, API references, and knowledge bases. It extends the base Site component with specialized components for navigation trees, search, versioning, and developer-focused features.

Naming Convention

DocsSite follows the ${SiteType}${Component} pattern:

DocsHeader = Header + search and version selector
DocsSidebar = Sidebar + navigation tree
DocsPage = Page + table of contents + edit links
DocsSearch = Search + documentation indexing
DocsNav = Nav + hierarchical structure

All docs components are the base component enhanced with documentation site-specific capabilities.

Type Definition

import type { DocsSite } from 'mdxui'

interface DocsSite extends BaseSite {
  type: 'docs'
  docs?: {
    repository?: string       // GitHub repository (e.g., "owner/repo")
    branch?: string          // Default branch for edit links (default: "main")
    search?: boolean         // Enable search (default: true)
    versioning?: boolean     // Enable version switching (default: false)
  }
}

Usage

Basic Example

import { Site, DocsPage, DocsSidebar, TableOfContents } from '@mdxui/beacon'

<Site
  type="docs"
  name="Acme Docs"
  docs={{
    repository: "acme/docs",
    branch: "main",
    search: true
  }}
>
  <DocsPage>
    <DocsSidebar navigation={docsNav} />
    <main>
      <h1>Getting Started</h1>
      <p>Welcome to the Acme documentation...</p>
    </main>
    <TableOfContents />
  </DocsPage>
</Site>

With Versioning

<Site
  type="docs"
  name="API Documentation"
  docs={{
    repository: "acme/api-docs",
    search: true,
    versioning: true
  }}
>
  <DocsPage version="v2.0">
    {/* Version-specific content */}
  </DocsPage>
</Site>

Required Components

DocsSite requires these specialized components:

DocsHeader

Required: Yes

Documentation header with search and version selector.

<DocsHeader
  logo={<Logo />}
  search={true}
  versions={["v2.0", "v1.9", "v1.8"]}
  currentVersion="v2.0"
  navigation={[
    { label: "Docs", href: "/docs" },
    { label: "API", href: "/api" },
    { label: "Guides", href: "/guides" }
  ]}
/>

DocsSidebar

Required: Yes

Sidebar navigation tree with collapsible sections.

<DocsSidebar
  navigation={[
    {
      title: "Getting Started",
      items: [
        { title: "Installation", href: "/docs/installation" },
        { title: "Quick Start", href: "/docs/quickstart" }
      ]
    },
    {
      title: "Core Concepts",
      items: [
        { title: "Components", href: "/docs/components" },
        { title: "Props", href: "/docs/props" }
      ]
    }
  ]}
  currentPath="/docs/installation"
/>

DocsPage

Required: Yes

Documentation page layout with breadcrumbs and metadata.

<DocsPage
  title="Installation"
  description="Learn how to install Acme in your project"
  breadcrumbs={[
    { label: "Home", href: "/" },
    { label: "Docs", href: "/docs" },
    { label: "Installation", href: "/docs/installation" }
  ]}
>
  {/* Page content */}
</DocsPage>

Optional Components

Breadcrumbs

Navigation breadcrumbs showing page hierarchy.

<Breadcrumbs
  items={[
    { label: "Docs", href: "/docs" },
    { label: "Components", href: "/docs/components" },
    { label: "Button", href: "/docs/components/button" }
  ]}
/>

PrevNext

Previous/Next page navigation at bottom.

<PrevNext
  prev={{ title: "Installation", href: "/docs/installation" }}
  next={{ title: "Configuration", href: "/docs/configuration" }}
/>

EditPage

"Edit this page" link to GitHub.

<EditPage
  repository="acme/docs"
  branch="main"
  path="docs/installation.mdx"
/>

CodeBlock

Syntax-highlighted code blocks with copy button.

<CodeBlock
  language="tsx"
  code={`import { Button } from '@acme/ui'

<Button variant="primary">
  Click me
</Button>`}
  showLineNumbers={true}
  highlightLines={[3, 4, 5]}
/>

Component Specializations

DocsHeader

Base Header component + documentation features.

// Enhanced with:
- Full-text search with keyboard shortcuts (⌘K)
- Version selector dropdown
- Theme toggle (light/dark)
- Mobile-responsive navigation
- Breadcrumbs integration

DocsSidebar

Base Sidebar component + navigation tree.

// Enhanced with:
- Hierarchical navigation structure
- Collapsible sections
- Active page highlighting
- Scroll position persistence
- Search filtering

DocsPage

Base Page component + documentation metadata.

// Enhanced with:
- Automatic breadcrumbs
- Last updated timestamp
- Edit on GitHub link
- Table of contents generation
- Reading time estimate

DocsSearch

Search component with documentation indexing.

// Enhanced with:
- Full-text search across all pages
- Keyboard navigation (↑↓ arrows)
- Search result highlighting
- Category filtering
- Recent searches

Search Integration

Built-in Search

DocsSite includes full-text search:

<Site
  type="docs"
  docs={{
    search: true  // Enables search
  }}
>
  {/* Search automatically indexes all DocsPage content */}
</Site>

Search Configuration

<DocsSearch
  placeholder="Search documentation..."
  shortcuts={["⌘K", "Ctrl+K"]}
  categories={["Docs", "API", "Guides"]}
  recentSearches={true}
  maxResults={10}
/>

Custom Search Provider

import { Algolia, Meilisearch } from '@mdxui/search'

<Site
  type="docs"
  docs={{
    search: true,
    searchProvider: new Algolia({
      appId: "XXX",
      apiKey: "YYY",
      indexName: "docs"
    })
  }}
>

Versioning

Version Selector

<DocsHeader
  versions={[
    { label: "v2.0", value: "v2.0", current: true },
    { label: "v1.9", value: "v1.9" },
    { label: "v1.8 (deprecated)", value: "v1.8", deprecated: true }
  ]}
  onVersionChange={(version) => {
    // Navigate to versioned docs
    window.location.href = `/docs/${version}`
  }}
/>

Version-Specific Content

<DocsPage version="v2.0">
  {version === "v2.0" && (
    <Callout type="info">
      This is the latest version. See the [migration guide](/docs/migration) to upgrade.
    </Callout>
  )}

  {version === "v1.9" && (
    <Callout type="warning">
      This version is in maintenance mode. Upgrade to v2.0 for new features.
    </Callout>
  )}
</DocsPage>

const docsNav = [
  {
    title: "Getting Started",
    collapsed: false,
    items: [
      { title: "Introduction", href: "/docs" },
      { title: "Installation", href: "/docs/installation" },
      { title: "Quick Start", href: "/docs/quickstart" }
    ]
  },
  {
    title: "Core Concepts",
    collapsed: false,
    items: [
      { title: "Components", href: "/docs/components" },
      { title: "Props", href: "/docs/props" },
      { title: "Styling", href: "/docs/styling" }
    ]
  },
  {
    title: "API Reference",
    collapsed: true,
    items: [
      {
        title: "Primitives",
        items: [
          { title: "Button", href: "/docs/api/button" },
          { title: "Input", href: "/docs/api/input" }
        ]
      }
    ]
  }
]

<DocsSidebar navigation={docsNav} />

GitHub Integration

Edit Links

Automatically generate "Edit this page" links:

<Site
  type="docs"
  docs={{
    repository: "acme/docs",
    branch: "main"
  }}
>
  <DocsPage path="docs/installation.mdx">
    {/* Generates: https://github.com/acme/docs/edit/main/docs/installation.mdx */}
  </DocsPage>
</Site>

Contributors

Show page contributors from Git history:

<DocsPage>
  <Contributors
    repository="acme/docs"
    path="docs/installation.mdx"
  />
</DocsPage>

Last Updated

Display last update timestamp:

<DocsPage>
  <LastUpdated
    repository="acme/docs"
    path="docs/installation.mdx"
  />
</DocsPage>

Best Practices

Keep hierarchy shallow: Max 3 levels deep
Group logically: Related topics together
Order by learning path: Basic → Advanced
Use descriptive titles: Clear, scannable labels
Limit top-level items: 5-7 main categories

Search Optimization

Write clear titles: Descriptive page titles
Use headings: Proper heading hierarchy (H1 → H6)
Include keywords: Natural keyword placement
Add descriptions: Meta descriptions for context
Link related content: Internal linking

Content Organization

One concept per page: Focus on single topics
Start with overview: High-level introduction first
Include examples: Code samples for every concept
Show progressive complexity: Simple → Advanced
Link to related docs: Help users discover content

Real-World Example

Complete documentation site:

import {
  Site,
  DocsHeader,
  DocsSidebar,
  DocsPage,
  TableOfContents,
  CodeBlock,
  Breadcrumbs,
  PrevNext,
  EditPage
} from '@mdxui/beacon'

const docsNav = [
  {
    title: "Getting Started",
    items: [
      { title: "Introduction", href: "/docs" },
      { title: "Installation", href: "/docs/installation" },
      { title: "Quick Start", href: "/docs/quickstart" }
    ]
  },
  {
    title: "Components",
    items: [
      { title: "Button", href: "/docs/components/button" },
      { title: "Input", href: "/docs/components/input" },
      { title: "Dialog", href: "/docs/components/dialog" }
    ]
  }
]

<Site
  type="docs"
  name="Acme Documentation"
  docs={{
    repository: "acme/docs",
    branch: "main",
    search: true,
    versioning: true
  }}
>
  <DocsHeader
    logo={<Logo />}
    search={true}
    versions={["v2.0", "v1.9"]}
    currentVersion="v2.0"
  />

  <div className="docs-layout">
    <DocsSidebar
      navigation={docsNav}
      currentPath="/docs/installation"
    />

    <main className="docs-content">
      <DocsPage
        title="Installation"
        description="Learn how to install Acme in your project"
      >
        <Breadcrumbs
          items={[
            { label: "Docs", href: "/docs" },
            { label: "Installation", href: "/docs/installation" }
          ]}
        />

        <h1>Installation</h1>
        <p>Get started by installing Acme via npm or yarn.</p>

        <h2>npm</h2>
        <CodeBlock
          language="bash"
          code="npm install @acme/ui"
        />

        <h2>yarn</h2>
        <CodeBlock
          language="bash"
          code="yarn add @acme/ui"
        />

        <PrevNext
          prev={{ title: "Introduction", href: "/docs" }}
          next={{ title: "Quick Start", href: "/docs/quickstart" }}
        />

        <EditPage
          repository="acme/docs"
          branch="main"
          path="docs/installation.mdx"
        />
      </DocsPage>
    </main>

    <TableOfContents
      headings={[
        { id: "npm", title: "npm", level: 2 },
        { id: "yarn", title: "yarn", level: 2 }
      ]}
    />
  </div>
</Site>

TypeScript

Full type definition:

import { z } from 'zod'
import { BaseSiteSchema } from 'mdxui/zod'

export const DocsSiteSchema = BaseSiteSchema.extend({
  type: z.literal('docs'),
  docs: z.object({
    repository: z.string().optional(),
    branch: z.string().default('main'),
    search: z.boolean().default(true),
    versioning: z.boolean().default(false),
  }).optional(),
})

export type DocsSite = z.infer<typeof DocsSiteSchema>

Site Component - Base site configuration
DocsPage Component - Documentation page details
Sidebar Component - Sidebar navigation
Search Component - Search functionality

DocsSite Specialization

On this page