Advanced Features

📖5 min read

📅Last updated: Jan 2, 2026

This comprehensive guide covers advanced features and techniques in EmberDocs. This document is intentionally longer to demonstrate scrolling behavior and table of contents functionality.

Custom Components

EmberDocs allows you to create custom React components and use them in your documentation:

typescript

// components/Alert.tsx
export function Alert({
  type = 'info',
  children
}: {
  type: 'info' | 'warning' | 'error'
  children: React.ReactNode
}) {
  const colors = {
    info: 'bg-blue-100 text-blue-900',
    warning: 'bg-yellow-100 text-yellow-900',
    error: 'bg-red-100 text-red-900',
  };

  return (
    <div className={`p-4 rounded ${colors[type]}`}>
      {children}
    </div>
  );
}

You can then import and use this component in your Markdown:

markdown

<Alert type="warning">
  This is an important warning!
</Alert>

Component Best Practices

Keep components simple - Complex logic should live elsewhere
Use TypeScript - Type safety is crucial
Document props - Always document component properties
Test thoroughly - Components are used in documentation

Search Optimization

The search index is built at compile time and includes all document content. To optimize search:

1. Use Descriptive Titles

Clear titles help search distinguish documents:

yaml

---
title: "How to Configure Authentication with OAuth 2.0"
slug: "guides/oauth-setup"
---

2. Include Keywords in Headings

Search weights headings higher than body text:

markdown

# OAuth 2.0 Authentication Setup
## Configuring OAuth Providers
### Google OAuth Configuration
### GitHub OAuth Configuration

3. Write Complete Sentences

Search works better with natural language:

markdown

# ❌ Bad
Installation Steps. Prerequisites. Node Version.

# ✅ Good
Follow these installation steps to set up EmberDocs. You'll need Node.js version 18 or higher before proceeding.

Search Index Customization

Configure search indexing behavior in your build script:

typescript

import { buildSearchIndex } from '@/lib/search';

const index = await buildSearchIndex('./docs', {
  maxBodyWords: 500,      // Limit body text
  titleWeight: 3,         // Title importance
  headingWeight: 2,       // Heading importance
  generateExcerpts: true, // Show previews
});

Versioning Your Documentation

EmberDocs supports multiple documentation versions using Git tags:

bash

# Tag a version
git tag v1.0.0

# Create a new version
git tag v2.0.0

# Switch between versions
git checkout v1.0.0

Your build process automatically detects and displays versions.

Version Configuration

typescript

// next.config.js
export default {
  async redirects() {
    return [
      {
        source: '/docs/:path*',
        destination: '/docs/v2.0.0/:path*',
        permanent: false,
      },
    ];
  },
};

Dark Mode Implementation

EmberDocs includes built-in dark mode support using CSS custom properties and the data-theme attribute:

Light Mode (Default)

css

:root {
  --bg: #FFFFFF;
  --text: #111827;
  --accent: #8B5CF6;
  --border: #E5E7EB;
}

Dark Mode

css

[data-theme="dark"] {
  --bg: #0F172A;
  --text: #F1F5F9;
  --accent: #8B5CF6;
  --border: #334155;
}

Toggling Theme

typescript

const toggleTheme = () => {
  const currentTheme = document.documentElement.getAttribute('data-theme');
  const newTheme = currentTheme === 'dark' ? 'light' : 'dark';
  document.documentElement.setAttribute('data-theme', newTheme);
  localStorage.setItem('theme', newTheme);
};

Performance Optimization

Image Optimization

Use Next.js Image component for all documentation images:

typescript

import Image from 'next/image';

export function DocImage() {
  return (
    <Image
      src="/docs/architecture.png"
      alt="System architecture diagram"
      width={800}
      height={600}
      priority
    />
  );
}

Code Splitting

Keep large components lazy-loaded:

typescript

import dynamic from 'next/dynamic';

const HeavyComponent = dynamic(() => import('./Heavy'), {
  loading: () => <p>Loading...</p>,
});

Build Optimization

EmberDocs optimizes at build time:

bash

# Build for production
npm run build

# Preview production build
npm run start

Note: For bundle size analysis, use @next/bundle-analyzer (install separately if needed).

Search Keyboard Shortcuts

Implement keyboard navigation for better UX:

typescript

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

    if (event.key === 'Escape') {
      closeSearch();
    }
  };

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

API Integration

Integrate with external APIs in your documentation:

typescript

// lib/api.ts
export async function fetchLatestVersion(): Promise<string> {
  const response = await fetch('https://api.github.com/repos/sturdy-barnacle/emberdocs/releases/latest');
  const data = await response.json();
  return data.tag_name;
}

Then use in documentation:

typescript

// components/LatestVersion.tsx
import { fetchLatestVersion } from '@/lib/api';

export async function LatestVersion() {
  const version = await fetchLatestVersion();
  return <span>Latest: {version}</span>;
}

Analytics Integration

Track documentation usage with analytics:

typescript

'use client';

import { useEffect } from 'react';

export function Analytics() {
  useEffect(() => {
    // Track page view
    if (typeof window !== 'undefined') {
      const event = new CustomEvent('doc-view', {
        detail: {
          path: window.location.pathname,
          timestamp: new Date().toISOString(),
        },
      });
      window.dispatchEvent(event);
    }
  }, []);

  return null;
}

Testing Documentation

Write tests for your documentation components:

typescript

// components/Alert.test.tsx
import { render, screen } from '@testing-library/react';
import { Alert } from './Alert';

describe('Alert', () => {
  it('renders with correct styling', () => {
    render(<Alert type="info">Test message</Alert>);
    expect(screen.getByText('Test message')).toBeInTheDocument();
  });
});

Accessibility

Ensure documentation is accessible:

Heading Hierarchy

markdown

# Main heading (H1)
## Subheading (H2)
### Sub-subheading (H3)

Alternative Text

markdown

![Architecture diagram showing component relationships](./diagram.png)

ARIA Labels

typescript

<button aria-label="Search documentation">
  🔍
</button>

SEO Best Practices

Optimize documentation for search engines:

Meta Tags

typescript

export const metadata: Metadata = {
  title: 'EmberDocs - Modern Documentation Framework',
  description: 'Build beautiful documentation with Git versioning and instant search',
  keywords: ['documentation', 'next.js', 'typescript'],
};

Structured Data

json

{
  "@context": "https://schema.org",
  "@type": "SoftwareSourceCode",
  "name": "EmberDocs",
  "description": "Modern documentation framework",
  "license": "Proprietary"
}

Migration Guide

Migrating from other documentation platforms:

From Docusaurus

Export your Markdown files
Update frontmatter format
Convert custom components to React
Test search functionality

From GitBook

Download Markdown export
Restructure directories as needed
Add YAML frontmatter
Update internal links

Troubleshooting Advanced Features

Search not working

Ensure public/search-index.json exists
Check browser console for fetch errors
Rebuild search index: npm run build:search

Dark mode not applying

Check data-theme attribute on <html>
Verify CSS custom properties in :root and [data-theme="dark"]
Clear browser cache

Components not rendering

Check component exports
Verify imports use correct paths
Check TypeScript types

Performance Metrics

Monitor documentation performance:

bash

# Lighthouse audit
npm install -g lighthouse
lighthouse https://docs.example.com

Next Steps

Explore API Reference
Check Troubleshooting
Review the Components guide

This comprehensive guide should demonstrate adequate scrolling behavior and table of contents functionality for testing purposes.