VoiceAssist Documentation Site - Feature Specifications

Document Version: 1.0.0 Last Updated: 2025-11-21 Status: Planning Phase

Table of Contents

1. Overview
2. Content Management Features
3. Interactive Elements Features
4. Navigation Features
5. Technical Implementation
6. Content Structure
7. Deployment Strategy

Overview

Technology Stack

The VoiceAssist Documentation Site is built on a modern, performant stack optimized for content-rich documentation:

Core Framework:

• Next.js 14 with App Router for enhanced performance and React Server Components
• React 18 with concurrent features
• TypeScript for type safety

Content Management:

• MDX for rich, interactive documentation
• Contentlayer for type-safe content transformation
• Gray-matter for frontmatter parsing

Styling:

• Tailwind CSS 3.4+ for utility-first styling
• CSS Variables for theming
• Tailwind Typography for prose styling

Search:

• Algolia DocSearch for instant, typo-tolerant search
• Keyboard shortcuts (Cmd+K / Ctrl+K)

Syntax Highlighting:

• Shiki for beautiful code highlighting
• Multiple themes support (light/dark)

Diagrams:

• Mermaid.js for flowcharts, sequence diagrams, and more

Deployment:

• Vercel for zero-config deployments
• Cloudflare CDN as alternative

Architecture Goals

1. Performance First: Sub-second page loads, optimized images, streaming SSR
2. Developer Experience: Hot reload, type safety, clear component architecture
3. Content Flexibility: Easy authoring in MDX with rich components
4. Accessibility: WCAG 2.1 AA compliance, keyboard navigation
5. SEO Optimized: Semantic HTML, meta tags, sitemap generation
6. Scalability: Support 1000+ pages without performance degradation

Project Structure

voiceassist-docs/
├── app/                          # Next.js 14 App Router
│   ├── layout.tsx               # Root layout
│   ├── page.tsx                 # Homepage
│   ├── docs/                    # Documentation routes
│   │   ├── layout.tsx          # Docs layout with sidebar
│   │   └── [...slug]/          # Dynamic doc pages
│   │       └── page.tsx
│   ├── api/                     # API routes
│   │   └── search/
│   └── globals.css              # Global styles
├── components/                   # React components
│   ├── MDXComponents.tsx        # MDX component mapping
│   ├── Navigation/              # Navigation components
│   ├── Interactive/             # Interactive elements
│   └── Layout/                  # Layout components
├── content/                      # MDX content
│   ├── docs/
│   │   ├── getting-started/
│   │   ├── api-reference/
│   │   └── guides/
│   └── blog/
├── contentlayer.config.ts       # Contentlayer configuration
├── lib/                          # Utility functions
├── public/                       # Static assets
└── styles/                       # Additional styles

Content Management Features

Feature 1.1: MDX-based Content System

Priority: P0 (Critical) Effort: 3 days Dependencies: Next.js 14, Contentlayer

Specification

A robust MDX-based content system that allows technical writers to create rich documentation with React components embedded in Markdown. The system must support:

• Standard Markdown syntax (GFM)
• React component imports and usage
• Frontmatter metadata
• Code blocks with syntax highlighting
• Automatic slug generation
• Type-safe content queries

Implementation

contentlayer.config.ts:

import { defineDocumentType, makeSource } from "contentlayer/source-files";
import rehypeAutolinkHeadings from "rehype-autolink-headings";
import rehypePrettyCode from "rehype-pretty-code";
import rehypeSlug from "rehype-slug";
import remarkGfm from "remark-gfm";

export const Doc = defineDocumentType(() => ({
  name: "Doc",
  filePathPattern: `docs/**/*.mdx`,
  contentType: "mdx",
  fields: {
    title: {
      type: "string",
      required: true,
    },
    description: {
      type: "string",
      required: true,
    },
    category: {
      type: "enum",
      options: ["getting-started", "api-reference", "guides", "examples"],
      required: true,
    },
    order: {
      type: "number",
      required: false,
    },
    published: {
      type: "boolean",
      default: true,
    },
    tags: {
      type: "list",
      of: { type: "string" },
    },
    author: {
      type: "string",
      required: false,
    },
    lastModified: {
      type: "date",
      required: false,
    },
    version: {
      type: "string",
      required: false,
    },
  },
  computedFields: {
    slug: {
      type: "string",
      resolve: (doc) => doc._raw.flattenedPath.replace(/^docs\//, ""),
    },
    slugAsParams: {
      type: "string",
      resolve: (doc) => doc._raw.flattenedPath.split("/").slice(1).join("/"),
    },
    url: {
      type: "string",
      resolve: (doc) => `/docs/${doc._raw.flattenedPath.replace(/^docs\//, "")}`,
    },
    headings: {
      type: "json",
      resolve: async (doc) => {
        const headingsRegex = /^(#{1,6})\s+(.+)$/gm;
        const headings: { level: number; text: string; slug: string }[] = [];
        let match;

        while ((match = headingsRegex.exec(doc.body.raw)) !== null) {
          const level = match[1].length;
          const text = match[2];
          const slug = text
            .toLowerCase()
            .replace(/[^a-z0-9]+/g, "-")
            .replace(/(^-|-$)/g, "");

          headings.push({ level, text, slug });
        }

        return headings;
      },
    },
  },
}));

export default makeSource({
  contentDirPath: "./content",
  documentTypes: [Doc],
  mdx: {
    remarkPlugins: [remarkGfm],
    rehypePlugins: [
      rehypeSlug,
      [
        rehypePrettyCode,
        {
          theme: {
            dark: "github-dark-dimmed",
            light: "github-light",
          },
          keepBackground: false,
        },
      ],
      [
        rehypeAutolinkHeadings,
        {
          behavior: "wrap",
          properties: {
            className: ["anchor"],
          },
        },
      ],
    ],
  },
});

components/MDXComponents.tsx:

import Image from 'next/image'
import Link from 'next/link'
import { Callout } from './Callout'
import { CodeBlock } from './CodeBlock'
import { CodePlayground } from './CodePlayground'
import { Tabs, Tab } from './Tabs'
import { Steps } from './Steps'

const components = {
  // HTML elements
  h1: ({ children, ...props }: any) => (
    <h1 className="text-4xl font-bold tracking-tight mt-8 mb-4" {...props}>
      {children}
    </h1>
  ),
  h2: ({ children, ...props }: any) => (
    <h2 className="text-3xl font-semibold tracking-tight mt-10 mb-4 border-b pb-2" {...props}>
      {children}
    </h2>
  ),
  h3: ({ children, ...props }: any) => (
    <h3 className="text-2xl font-semibold tracking-tight mt-8 mb-3" {...props}>
      {children}
    </h3>
  ),
  h4: ({ children, ...props }: any) => (
    <h4 className="text-xl font-semibold tracking-tight mt-6 mb-2" {...props}>
      {children}
    </h4>
  ),
  p: ({ children, ...props }: any) => (
    <p className="leading-7 mb-4" {...props}>
      {children}
    </p>
  ),
  a: ({ href, children, ...props }: any) => {
    const isExternal = href?.startsWith('http')
    const Component = isExternal ? 'a' : Link

    return (
      <Component
        href={href}
        className="font-medium text-blue-600 hover:text-blue-800 dark:text-blue-400 dark:hover:text-blue-300 underline underline-offset-4"
        {...(isExternal && { target: '_blank', rel: 'noopener noreferrer' })}
        {...props}
      >
        {children}
      </Component>
    )
  },
  ul: ({ children, ...props }: any) => (
    <ul className="list-disc list-inside space-y-2 mb-4" {...props}>
      {children}
    </ul>
  ),
  ol: ({ children, ...props }: any) => (
    <ol className="list-decimal list-inside space-y-2 mb-4" {...props}>
      {children}
    </ol>
  ),
  li: ({ children, ...props }: any) => (
    <li className="leading-7" {...props}>
      {children}
    </li>
  ),
  code: ({ children, className, ...props }: any) => {
    // Inline code
    if (!className) {
      return (
        <code
          className="relative rounded bg-gray-100 dark:bg-gray-800 px-[0.3rem] py-[0.2rem] font-mono text-sm"
          {...props}
        >
          {children}
        </code>
      )
    }

    // Block code (handled by rehype-pretty-code)
    return <code className={className} {...props}>{children}</code>
  },
  pre: ({ children, ...props }: any) => (
    <pre
      className="mb-4 overflow-x-auto rounded-lg bg-gray-900 dark:bg-gray-950 p-4"
      {...props}
    >
      {children}
    </pre>
  ),
  blockquote: ({ children, ...props }: any) => (
    <blockquote
      className="border-l-4 border-gray-300 dark:border-gray-700 pl-4 italic my-4"
      {...props}
    >
      {children}
    </blockquote>
  ),
  table: ({ children, ...props }: any) => (
    <div className="overflow-x-auto my-6">
      <table className="min-w-full divide-y divide-gray-200 dark:divide-gray-700" {...props}>
        {children}
      </table>
    </div>
  ),
  thead: ({ children, ...props }: any) => (
    <thead className="bg-gray-50 dark:bg-gray-800" {...props}>
      {children}
    </thead>
  ),
  th: ({ children, ...props }: any) => (
    <th
      className="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider"
      {...props}
    >
      {children}
    </th>
  ),
  td: ({ children, ...props }: any) => (
    <td className="px-6 py-4 whitespace-nowrap text-sm" {...props}>
      {children}
    </td>
  ),

  // Custom components
  Image: (props: any) => <Image {...props} />,
  Callout,
  CodeBlock,
  CodePlayground,
  Tabs,
  Tab,
  Steps,
}

export default components

app/docs/[...slug]/page.tsx:

import { notFound } from 'next/navigation'
import { allDocs } from 'contentlayer/generated'
import { Mdx } from '@/components/mdx-components'
import { TableOfContents } from '@/components/toc'
import { DocsPager } from '@/components/pager'
import { Metadata } from 'next'

interface DocPageProps {
  params: {
    slug: string[]
  }
}

async function getDocFromParams(params: DocPageProps['params']) {
  const slug = params.slug?.join('/') || ''
  const doc = allDocs.find((doc) => doc.slugAsParams === slug)

  if (!doc) {
    null
  }

  return doc
}

export async function generateMetadata({
  params,
}: DocPageProps): Promise<Metadata> {
  const doc = await getDocFromParams(params)

  if (!doc) {
    return {}
  }

  return {
    title: doc.title,
    description: doc.description,
    openGraph: {
      title: doc.title,
      description: doc.description,
      type: 'article',
      url: doc.url,
    },
    twitter: {
      card: 'summary_large_image',
      title: doc.title,
      description: doc.description,
    },
  }
}

export async function generateStaticParams(): Promise<DocPageProps['params'][]> {
  return allDocs.map((doc) => ({
    slug: doc.slugAsParams.split('/'),
  }))
}

export default async function DocPage({ params }: DocPageProps) {
  const doc = await getDocFromParams(params)

  if (!doc || !doc.published) {
    notFound()
  }

  return (
    <div className="flex gap-10">
      <article className="flex-1 min-w-0">
        <div className="mb-8">
          <h1 className="text-4xl font-bold tracking-tight">{doc.title}</h1>
          <p className="text-lg text-gray-600 dark:text-gray-400 mt-2">
            {doc.description}
          </p>
          {doc.version && (
            <div className="mt-2 text-sm text-gray-500">
              Version: {doc.version}
            </div>
          )}
        </div>

        <Mdx code={doc.body.code} />

        <DocsPager doc={doc} />
      </article>

      <aside className="hidden xl:block w-64 flex-shrink-0">
        <div className="sticky top-20">
          <TableOfContents headings={doc.headings} />
        </div>
      </aside>
    </div>
  )
}

Example MDX Content (content/docs/getting-started/installation.mdx):

---
title: Installation
description: Get started with VoiceAssist in minutes
category: getting-started
order: 1
published: true
tags: [setup, installation, quickstart]
version: "1.0.0"
---

import { Callout } from "@/components/Callout";
import { Steps } from "@/components/Steps";
import { Tabs, Tab } from "@/components/Tabs";

# Installation

Get VoiceAssist up and running in your project in just a few minutes.

<Callout type="info">Before you begin, make sure you have Node.js 18 or later installed.</Callout>

## Prerequisites

Ensure you have the following installed:

- Node.js 18.0.0 or later
- npm, yarn, or pnpm
- A modern browser (Chrome, Firefox, Safari, or Edge)

## Installation Steps

<Steps>

### Install the package

Choose your preferred package manager:

<Tabs>
  <Tab label="npm">
    ```bash
    npm install voiceassist
    ```
  </Tab>

<Tab label="yarn">```bash yarn add voiceassist ```</Tab>

  <Tab label="pnpm">
    ```bash
    pnpm add voiceassist
    ```
  </Tab>
</Tabs>

### Configure your API key

Create a `.env.local` file in your project root:

```env
VOICEASSIST_API_KEY=your_api_key_here
VOICEASSIST_REGION=us-east-1
```

Initialize the client

Create a new file lib/voiceassist.ts:

import { VoiceAssist } from "voiceassist";

export const voiceAssist = new VoiceAssist({
  apiKey: process.env.VOICEASSIST_API_KEY!,
  region: process.env.VOICEASSIST_REGION,
  options: {
    language: "en-US",
    enableLogging: process.env.NODE_ENV === "development",
  },
});

Verify installation

Run the following command to verify your setup:

npm run voiceassist:verify

Next Steps

Now that you have VoiceAssist installed, you can:

• Create your first voice command (see voice mode guides)
• Explore the API reference (see /ai/api)
• Check out examples (see usage documentation)

Feature 1.2: Version Control Integration

Priority: P1 (High) Effort: 2 days Dependencies: Git, GitHub/GitLab

Specification

Seamless version control integration that tracks content changes, enables collaboration, and maintains documentation history. Features include:

• Automatic last-modified timestamps
• Git-based edit history
• "Edit on GitHub" links
• Contributor attribution
• Content versioning for different product versions

Implementation

lib/git-utils.ts:

import { execSync } from "child_process";
import path from "path";

export interface GitFileInfo {
  lastModified: Date;
  author: string;
  authorEmail: string;
  commitHash: string;
  contributors: Array<{
    name: string;
    email: string;
    commits: number;
  }>;
}

export function getGitFileInfo(filePath: string): GitFileInfo | null {
  try {
    const absolutePath = path.join(process.cwd(), filePath);

    // Get last commit info
    const lastCommit = execSync(`git log -1 --format="%ai|%an|%ae|%H" -- "${absolutePath}"`, {
      encoding: "utf-8",
    }).trim();

    if (!lastCommit) return null;

    const [dateStr, author, authorEmail, commitHash] = lastCommit.split("|");

    // Get all contributors
    const contributorsOutput = execSync(`git log --format="%an|%ae" -- "${absolutePath}" | sort | uniq -c | sort -rn`, {
      encoding: "utf-8",
    }).trim();

    const contributors = contributorsOutput
      .split("\n")
      .filter(Boolean)
      .map((line) => {
        const match = line.trim().match(/^\s*(\d+)\s+(.+)\|(.+)$/);
        if (!match) return null;

        return {
          name: match[2],
          email: match[3],
          commits: parseInt(match[1], 10),
        };
      })
      .filter(Boolean) as GitFileInfo["contributors"];

    return {
      lastModified: new Date(dateStr),
      author,
      authorEmail,
      commitHash,
      contributors,
    };
  } catch (error) {
    console.error("Error getting git info:", error);
    return null;
  }
}

export function getEditUrl(filePath: string, repo: string): string {
  const branch = "main";
  return `https://github.com/${repo}/edit/${branch}/${filePath}`;
}

components/DocFooter.tsx:

'use client'

import { useState, useEffect } from 'react'
import Link from 'next/link'
import { GitBranch, Clock, Users, Github } from 'lucide-react'

interface DocFooterProps {
  filePath: string
  repository: string
  lastModified?: Date
  contributors?: Array<{
    name: string
    email: string
    commits: number
  }>
}

export function DocFooter({
  filePath,
  repository,
  lastModified,
  contributors = [],
}: DocFooterProps) {
  const [mounted, setMounted] = useState(false)

  useEffect(() => {
    setMounted(true)
  }, [])

  const editUrl = `https://github.com/${repository}/edit/main/${filePath}`
  const historyUrl = `https://github.com/${repository}/commits/main/${filePath}`

  const topContributors = contributors.slice(0, 3)

  return (
    <footer className="mt-12 pt-8 border-t border-gray-200 dark:border-gray-800">
      <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
        {/* Last Modified */}
        <div className="flex items-start gap-3">
          <Clock className="w-5 h-5 text-gray-400 mt-0.5" />
          <div>
            <h3 className="text-sm font-medium mb-1">Last Updated</h3>
            {mounted && lastModified ? (
              <time
                dateTime={lastModified.toISOString()}
                className="text-sm text-gray-600 dark:text-gray-400"
              >
                {lastModified.toLocaleDateString('en-US', {
                  year: 'numeric',
                  month: 'long',
                  day: 'numeric',
                })}
              </time>
            ) : (
              <span className="text-sm text-gray-600 dark:text-gray-400">
                Recently
              </span>
            )}
          </div>
        </div>

        {/* Contributors */}
        {topContributors.length > 0 && (
          <div className="flex items-start gap-3">
            <Users className="w-5 h-5 text-gray-400 mt-0.5" />
            <div>
              <h3 className="text-sm font-medium mb-1">Contributors</h3>
              <div className="flex flex-wrap gap-2">
                {topContributors.map((contributor) => (
                  <span
                    key={contributor.email}
                    className="text-sm text-gray-600 dark:text-gray-400"
                    title={`${contributor.commits} commits`}
                  >
                    {contributor.name}
                  </span>
                ))}
                {contributors.length > 3 && (
                  <span className="text-sm text-gray-500">
                    +{contributors.length - 3} more
                  </span>
                )}
              </div>
            </div>
          </div>
        )}
      </div>

      {/* Action Links */}
      <div className="flex flex-wrap gap-4 mt-6">
        <Link
          href={editUrl}
          target="_blank"
          rel="noopener noreferrer"
          className="inline-flex items-center gap-2 text-sm text-blue-600 hover:text-blue-800 dark:text-blue-400"
        >
          <Github className="w-4 h-4" />
          Edit this page
        </Link>

        <Link
          href={historyUrl}
          target="_blank"
          rel="noopener noreferrer"
          className="inline-flex items-center gap-2 text-sm text-blue-600 hover:text-blue-800 dark:text-blue-400"
        >
          <GitBranch className="w-4 h-4" />
          View history
        </Link>
      </div>
    </footer>
  )
}

Enhanced app/docs/[...slug]/page.tsx:

import { DocFooter } from '@/components/DocFooter'
import { getGitFileInfo } from '@/lib/git-utils'

export default async function DocPage({ params }: DocPageProps) {
  const doc = await getDocFromParams(params)

  if (!doc || !doc.published) {
    notFound()
  }

  // Get git info
  const gitInfo = getGitFileInfo(doc._raw.sourceFilePath)

  return (
    <div className="flex gap-10">
      <article className="flex-1 min-w-0">
        {/* ... existing content ... */}

        <DocFooter
          filePath={doc._raw.sourceFilePath}
          repository="yourusername/voiceassist"
          lastModified={gitInfo?.lastModified}
          contributors={gitInfo?.contributors}
        />
      </article>

      {/* ... sidebar ... */}
    </div>
  )
}

Feature 1.3: Multi-language Support

Priority: P2 (Medium) Effort: 4 days Dependencies: next-intl or similar

Specification

Comprehensive internationalization support for documentation in multiple languages. Features include:

• Language switcher in navigation
• Translated content with language-specific URLs
• Fallback to English for missing translations
• RTL support for Arabic and Hebrew
• Language-specific search indices

Implementation

i18n/config.ts:

export const locales = ["en", "ar", "es", "fr", "de", "zh"] as const;
export type Locale = (typeof locales)[number];

export const defaultLocale: Locale = "en";

export const localeNames: Record<Locale, string> = {
  en: "English",
  ar: "العربية",
  es: "Español",
  fr: "Français",
  de: "Deutsch",
  zh: "中文",
};

export const localeDirections: Record<Locale, "ltr" | "rtl"> = {
  en: "ltr",
  ar: "rtl",
  es: "ltr",
  fr: "ltr",
  de: "ltr",
  zh: "ltr",
};

Enhanced contentlayer.config.ts:

export const Doc = defineDocumentType(() => ({
  name: "Doc",
  filePathPattern: `docs/**/*.mdx`,
  contentType: "mdx",
  fields: {
    // ... existing fields ...
    locale: {
      type: "enum",
      options: ["en", "ar", "es", "fr", "de", "zh"],
      default: "en",
      required: true,
    },
    translationKey: {
      type: "string",
      required: false,
      description: "Key to link translations together",
    },
  },
  computedFields: {
    // ... existing computed fields ...
    localizedPath: {
      type: "string",
      resolve: (doc) => {
        const path = doc._raw.flattenedPath.replace(/^docs\//, "");
        return doc.locale === "en" ? path : `${doc.locale}/${path}`;
      },
    },
  },
}));

Content Structure:

content/
├── docs/
│   ├── en/
│   │   ├── getting-started/
│   │   │   └── installation.mdx
│   │   └── api-reference/
│   ├── ar/
│   │   ├── getting-started/
│   │   │   └── installation.mdx
│   │   └── api-reference/
│   └── es/
│       ├── getting-started/
│       └── api-reference/

components/LanguageSwitcher.tsx:

'use client'

import { useState } from 'react'
import { useRouter, usePathname } from 'next/navigation'
import { Globe } from 'lucide-react'
import { locales, localeNames, type Locale } from '@/i18n/config'

export function LanguageSwitcher({ currentLocale }: { currentLocale: Locale }) {
  const [isOpen, setIsOpen] = useState(false)
  const router = useRouter()
  const pathname = usePathname()

  const switchLocale = (newLocale: Locale) => {
    const segments = pathname.split('/').filter(Boolean)

    // Remove current locale if present
    if (locales.includes(segments[0] as Locale)) {
      segments.shift()
    }

    // Add new locale if not default
    const newPath = newLocale === 'en'
      ? `/${segments.join('/')}`
      : `/${newLocale}/${segments.join('/')}`

    router.push(newPath)
    setIsOpen(false)
  }

  return (
    <div className="relative">
      <button
        onClick={() => setIsOpen(!isOpen)}
        className="flex items-center gap-2 px-3 py-2 rounded-md hover:bg-gray-100 dark:hover:bg-gray-800"
        aria-label="Select language"
      >
        <Globe className="w-4 h-4" />
        <span className="text-sm font-medium">{localeNames[currentLocale]}</span>
      </button>

      {isOpen && (
        <>
          <div
            className="fixed inset-0 z-40"
            onClick={() => setIsOpen(false)}
          />
          <div className="absolute right-0 mt-2 w-48 rounded-md shadow-lg bg-white dark:bg-gray-800 ring-1 ring-black ring-opacity-5 z-50">
            <div className="py-1" role="menu">
              {locales.map((locale) => (
                <button
                  key={locale}
                  onClick={() => switchLocale(locale)}
                  className={`
                    block w-full text-left px-4 py-2 text-sm
                    ${locale === currentLocale
                      ? 'bg-gray-100 dark:bg-gray-700 font-medium'
                      : 'hover:bg-gray-50 dark:hover:bg-gray-700'
                    }
                  `}
                  role="menuitem"
                >
                  {localeNames[locale]}
                </button>
              ))}
            </div>
          </div>
        </>
      )}
    </div>
  )
}

app/[locale]/docs/[...slug]/page.tsx:

import { notFound } from 'next/navigation'
import { allDocs } from 'contentlayer/generated'
import { locales, defaultLocale, type Locale } from '@/i18n/config'

interface LocalizedDocPageProps {
  params: {
    locale: Locale
    slug: string[]
  }
}

async function getLocalizedDoc(locale: Locale, slug: string[]) {
  const slugStr = slug.join('/')

  // Try to find doc in requested locale
  let doc = allDocs.find(
    (d) => d.locale === locale && d.slugAsParams === slugStr
  )

  // Fallback to English if not found
  if (!doc && locale !== defaultLocale) {
    doc = allDocs.find(
      (d) => d.locale === defaultLocale && d.slugAsParams === slugStr
    )
  }

  return doc
}

export async function generateStaticParams() {
  const params: LocalizedDocPageProps['params'][] = []

  for (const locale of locales) {
    const localeDocs = allDocs.filter((doc) => doc.locale === locale)

    for (const doc of localeDocs) {
      params.push({
        locale,
        slug: doc.slugAsParams.split('/'),
      })
    }
  }

  return params
}

export default async function LocalizedDocPage({
  params,
}: LocalizedDocPageProps) {
  const doc = await getLocalizedDoc(params.locale, params.slug)

  if (!doc || !doc.published) {
    notFound()
  }

  // Find available translations
  const translations = doc.translationKey
    ? allDocs.filter((d) => d.translationKey === doc.translationKey && d.locale !== doc.locale)
    : []

  return (
    <div className="flex gap-10" dir={localeDirections[params.locale]}>
      <article className="flex-1 min-w-0">
        {translations.length > 0 && (
          <div className="mb-4 p-4 bg-blue-50 dark:bg-blue-900/20 rounded-md">
            <p className="text-sm text-blue-800 dark:text-blue-200">
              This page is also available in:{' '}
              {translations.map((t, i) => (
                <span key={t.locale}>
                  <Link href={t.url} className="underline">
                    {localeNames[t.locale as Locale]}
                  </Link>
                  {i < translations.length - 1 && ', '}
                </span>
              ))}
            </p>
          </div>
        )}

        {/* ... rest of content ... */}
      </article>
    </div>
  )
}

Feature 1.4: Content Search (Algolia DocSearch)

Priority: P0 (Critical) Effort: 2 days Dependencies: Algolia DocSearch

Specification

Fast, typo-tolerant search powered by Algolia DocSearch. Features include:

• Instant search results as you type
• Keyboard shortcuts (Cmd/Ctrl + K)
• Categorized results (sections, pages, headings)
• Search highlighting
• Recent searches
• Mobile-responsive search modal

Implementation

components/Search.tsx:

'use client'

import { useEffect, useRef, useCallback } from 'react'
import { DocSearch } from '@docsearch/react'
import '@docsearch/css'

interface SearchProps {
  appId?: string
  apiKey?: string
  indexName?: string
}

export function Search({
  appId = process.env.NEXT_PUBLIC_ALGOLIA_APP_ID,
  apiKey = process.env.NEXT_PUBLIC_ALGOLIA_SEARCH_KEY,
  indexName = process.env.NEXT_PUBLIC_ALGOLIA_INDEX_NAME,
}: SearchProps) {
  const searchButtonRef = useRef<HTMLButtonElement>(null)

  const onOpen = useCallback(() => {
    if (searchButtonRef.current) {
      searchButtonRef.current.click()
    }
  }, [])

  useEffect(() => {
    const handleKeyDown = (e: KeyboardEvent) => {
      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
        e.preventDefault()
        onOpen()
      }
    }

    window.addEventListener('keydown', handleKeyDown)
    return () => window.removeEventListener('keydown', handleKeyDown)
  }, [onOpen])

  if (!appId || !apiKey || !indexName) {
    return null
  }

  return (
    <DocSearch
      appId={appId}
      apiKey={apiKey}
      indexName={indexName}
      placeholder="Search documentation..."
      translations={{
        button: {
          buttonText: 'Search',
          buttonAriaLabel: 'Search documentation',
        },
      }}
    />
  )
}

export function SearchTrigger() {
  return (
    <button
      type="button"
      className="group flex items-center gap-3 px-4 py-2 w-full max-w-md text-sm text-gray-600 dark:text-gray-400 bg-white dark:bg-gray-800 border border-gray-300 dark:border-gray-700 rounded-lg hover:border-gray-400 dark:hover:border-gray-600 focus:outline-none focus:ring-2 focus:ring-blue-500"
      onClick={() => {
        const searchButton = document.querySelector('.DocSearch-Button') as HTMLButtonElement
        searchButton?.click()
      }}
    >
      <svg
        className="w-5 h-5"
        fill="none"
        stroke="currentColor"
        viewBox="0 0 24 24"
      >
        <path
          strokeLinecap="round"
          strokeLinejoin="round"
          strokeWidth={2}
          d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"
        />
      </svg>
      <span className="flex-1 text-left">Search docs...</span>
      <kbd className="hidden sm:inline-flex items-center gap-1 px-2 py-1 text-xs font-medium text-gray-500 bg-gray-100 dark:bg-gray-700 border border-gray-200 dark:border-gray-600 rounded">
        <span>⌘</span>K
      </kbd>
    </button>
  )
}

styles/docsearch.css (Customizations):

:root {
  --docsearch-primary-color: rgb(59, 130, 246);
  --docsearch-text-color: rgb(31, 41, 55);
  --docsearch-spacing: 12px;
  --docsearch-icon-stroke-width: 1.4;
  --docsearch-highlight-color: var(--docsearch-primary-color);
  --docsearch-muted-color: rgb(107, 114, 128);
  --docsearch-container-background: rgba(0, 0, 0, 0.6);
  --docsearch-modal-background: rgb(255, 255, 255);
  --docsearch-searchbox-background: rgb(249, 250, 251);
  --docsearch-searchbox-focus-background: rgb(255, 255, 255);
  --docsearch-hit-color: rgb(31, 41, 55);
  --docsearch-hit-active-color: rgb(255, 255, 255);
  --docsearch-hit-background: rgb(255, 255, 255);
  --docsearch-hit-shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1);
  --docsearch-key-gradient: linear-gradient(-225deg, rgb(249, 250, 251), rgb(243, 244, 246));
  --docsearch-key-shadow:
    inset 0 -2px 0 0 rgb(209, 213, 219), inset 0 0 1px 1px rgb(255, 255, 255), 0 1px 2px 1px rgba(0, 0, 0, 0.1);
  --docsearch-footer-background: rgb(249, 250, 251);
}

.dark {
  --docsearch-text-color: rgb(243, 244, 246);
  --docsearch-container-background: rgba(0, 0, 0, 0.8);
  --docsearch-modal-background: rgb(31, 41, 55);
  --docsearch-modal-shadow: inset 1px 1px 0 0 rgb(55, 65, 81), 0 3px 8px 0 rgba(0, 0, 0, 0.66);
  --docsearch-searchbox-background: rgb(17, 24, 39);
  --docsearch-searchbox-focus-background: rgb(0, 0, 0);
  --docsearch-hit-color: rgb(243, 244, 246);
  --docsearch-hit-shadow: none;
  --docsearch-hit-background: rgb(55, 65, 81);
  --docsearch-key-gradient: linear-gradient(-26.5deg, rgb(55, 65, 81), rgb(31, 41, 55));
  --docsearch-key-shadow:
    inset 0 -2px 0 0 rgb(17, 24, 39), inset 0 0 1px 1px rgb(75, 85, 99), 0 2px 2px 0 rgba(0, 0, 0, 0.3);
  --docsearch-footer-background: rgb(17, 24, 39);
  --docsearch-footer-shadow: inset 0 1px 0 0 rgb(55, 65, 81), 0 -4px 8px 0 rgba(0, 0, 0, 0.2);
  --docsearch-muted-color: rgb(156, 163, 175);
}

.DocSearch-Button {
  margin: 0;
  border-radius: 0.5rem;
}

.DocSearch-Button-Keys {
  min-width: auto;
  padding: 0;
}

.DocSearch-Hit-icon {
  display: flex;
  align-items: center;
}

.DocSearch-Hit[aria-selected="true"] {
  background: var(--docsearch-primary-color);
}

.DocSearch-Hit[aria-selected="true"] .DocSearch-Hit-title,
.DocSearch-Hit[aria-selected="true"] .DocSearch-Hit-path {
  color: var(--docsearch-hit-active-color);
}

Algolia Configuration (docsearch.json):

{
  "index_name": "voiceassist",
  "start_urls": [
    {
      "url": "https://docs.voiceassist.io/",
      "selectors_key": "homepage"
    },
    {
      "url": "https://docs.voiceassist.io/docs/",
      "selectors_key": "docs"
    }
  ],
  "sitemap_urls": ["https://docs.voiceassist.io/sitemap.xml"],
  "selectors": {
    "homepage": {
      "lvl0": ".hero h1",
      "lvl1": ".features h2",
      "lvl2": ".features h3",
      "text": ".features p"
    },
    "docs": {
      "lvl0": {
        "selector": ".sidebar .active",
        "default_value": "Documentation"
      },
      "lvl1": "article h1",
      "lvl2": "article h2",
      "lvl3": "article h3",
      "lvl4": "article h4",
      "lvl5": "article h5",
      "text": "article p, article li"
    }
  },
  "selectors_exclude": [".hash-link", ".table-of-contents", ".DocSearch-Button", "footer"],
  "custom_settings": {
    "attributesForFaceting": ["language", "version", "category"],
    "attributesToRetrieve": ["hierarchy", "content", "anchor", "url", "url_without_anchor", "type"],
    "attributesToHighlight": ["hierarchy", "content"],
    "attributesToSnippet": ["content:20"],
    "highlightPreTag": "<mark>",
    "highlightPostTag": "</mark>",
    "minWordSizefor1Typo": 3,
    "minWordSizefor2Typos": 7,
    "hitsPerPage": 20,
    "maxValuesPerFacet": 100
  }
}

Feature 1.5: Table of Contents Generation

Priority: P1 (High) Effort: 1 day Dependencies: None

Specification

Automatic table of contents generation from document headings with:

• Smooth scroll navigation
• Active heading highlighting
• Nested hierarchy support (H2-H4)
• Collapsible sections
• Sticky positioning

Implementation

components/TableOfContents.tsx:

'use client'

import { useEffect, useState, useCallback } from 'react'
import { cn } from '@/lib/utils'

interface Heading {
  level: number
  text: string
  slug: string
}

interface TableOfContentsProps {
  headings: Heading[]
}

export function TableOfContents({ headings }: TableOfContentsProps) {
  const [activeId, setActiveId] = useState<string>('')

  const onClick = useCallback((e: React.MouseEvent<HTMLAnchorElement>, slug: string) => {
    e.preventDefault()
    const element = document.getElementById(slug)

    if (element) {
      const offset = 80 // Account for sticky header
      const elementPosition = element.getBoundingClientRect().top
      const offsetPosition = elementPosition + window.pageYOffset - offset

      window.scrollTo({
        top: offsetPosition,
        behavior: 'smooth',
      })

      // Update URL without jumping
      window.history.pushState(null, '', `#${slug}`)
    }
  }, [])

  useEffect(() => {
    const observer = new IntersectionObserver(
      (entries) => {
        entries.forEach((entry) => {
          if (entry.isIntersecting) {
            setActiveId(entry.target.id)
          }
        })
      },
      {
        rootMargin: '-100px 0px -80% 0px',
      }
    )

    headings.forEach(({ slug }) => {
      const element = document.getElementById(slug)
      if (element) {
        observer.observe(element)
      }
    })

    return () => observer.disconnect()
  }, [headings])

  if (!headings || headings.length === 0) {
    return null
  }

  // Filter to only show H2 and H3 headings
  const visibleHeadings = headings.filter((h) => h.level >= 2 && h.level <= 3)

  if (visibleHeadings.length === 0) {
    return null
  }

  return (
    <div className="space-y-2">
      <p className="font-medium text-sm text-gray-900 dark:text-gray-100 mb-3">
        On this page
      </p>
      <nav className="space-y-1">
        {visibleHeadings.map((heading) => (
          <a
            key={heading.slug}
            href={`#${heading.slug}`}
            onClick={(e) => onClick(e, heading.slug)}
            className={cn(
              'block text-sm py-1 transition-colors',
              heading.level === 3 && 'pl-4',
              activeId === heading.slug
                ? 'text-blue-600 dark:text-blue-400 font-medium'
                : 'text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-200'
            )}
          >
            {heading.text}
          </a>
        ))}
      </nav>
    </div>
  )
}

Enhanced contentlayer.config.ts (Heading extraction):

export const Doc = defineDocumentType(() => ({
  // ... existing fields ...
  computedFields: {
    // ... existing computed fields ...
    headings: {
      type: "json",
      resolve: async (doc) => {
        const headingsRegex = /^(#{1,6})\s+(.+)$/gm;
        const headings: { level: number; text: string; slug: string }[] = [];
        let match;

        while ((match = headingsRegex.exec(doc.body.raw)) !== null) {
          const level = match[1].length;
          const text = match[2]
            .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1") // Remove markdown links
            .replace(/`([^`]+)`/g, "$1") // Remove code formatting
            .replace(/<[^>]+>/g, "") // Remove HTML tags
            .trim();

          const slug = text
            .toLowerCase()
            .replace(/[^a-z0-9]+/g, "-")
            .replace(/(^-|-$)/g, "");

          headings.push({ level, text, slug });
        }

        return headings;
      },
    },
  },
}));