Implementing AI Metadata in Docusaurus

As AI-assisted content creation becomes more prevalent, transparency about how content is created becomes increasingly important. This post explains how we implemented a comprehensive AI metadata system in our Docusaurus blog, following theme conventions and providing clear visibility into AI involvement in content creation.

The Implementation Journey

Our journey to implement AI metadata tracking involved several key decisions and steps:

1. Following Docusaurus theme conventions
2. Using TypeScript for type safety
3. Creating a clear component hierarchy
4. Implementing proper metadata display

Theme Integration

We chose to integrate our AI metadata display as a theme component following Docusaurus conventions:

src/theme/
  BlogPost/
    Header/
      AIMetadata/
        index.tsx    # Main component
        types.ts     # Type definitions

This structure allows for:

• Clear organization
• Easy swizzling
• Future extensibility
• Proper theme integration

Front Matter Structure

We implemented a structured front matter format that captures essential information about AI involvement:

---
title: Your Blog Post Title
authors: [claude]  # AI author attribution
tags: [tag1, tag2]
# AI Metadata Fields
ai_generated: true
ai_models: 
  - name: "Claude 3.5 Sonnet"
    version: "20241022"
    tasks: ["content", "code"]
    confidence_score: 0.95
ai_tools:
  - name: "Anthropic Messages API"
    version: "2024-03"
ai_review_process: "Human reviewed and edited"
ai_quality_metrics:
  accuracy: 0.95
  coherence: 0.98
  technical_depth: 0.92
---

TypeScript Implementation

We use TypeScript interfaces to ensure type safety:

interface AIModel {
  name: string;
  version: string;
  tasks?: string[];
  confidence_score?: number;
}

interface AITool {
  name: string;
  version: string;
}

interface QualityMetrics {
  accuracy: number;
  coherence: number;
  technical_depth: number;
  [key: string]: number;
}

interface AIMetadata {
  ai_generated: boolean;
  ai_models?: AIModel[];
  ai_tools?: AITool[];
  ai_review_process?: string;
  ai_quality_metrics?: QualityMetrics;
}

Component Implementation

The component is implemented as a swizzled theme component:

import React from 'react';
import BlogPostHeader from '@theme-original/BlogPost/Header';
import type { WrapperProps } from '@docusaurus/types';
import AIMetadata from './AIMetadata';

export default function BlogPostHeaderWrapper(
  props: WrapperProps<typeof BlogPostHeader>
): JSX.Element {
  return (
    <>
      <AIMetadata metadata={props.metadata} />
      <BlogPostHeader {...props} />
    </>
  );
}

Integration Steps

1. Install required dependencies:

npm install @docusaurus/theme-classic zod @headlessui/react

2. Swizzle the BlogPost Header (note the --wrap option):

npm run swizzle @docusaurus/theme-classic BlogPost/Header -- --wrap

3. Implement the component structure:

src/theme/
  BlogPost/
    Header/
      AIMetadata/
        index.tsx
        types.ts
    index.tsx

Best Practices

1. Theme Integration

   • Use wrapping instead of ejection for better maintainability
   • Follow Docusaurus naming conventions
   • Keep components modular

2. Type Safety

   • Use TypeScript throughout
   • Define clear interfaces
   • Validate metadata structure

3. Component Organization

   • Follow theme hierarchy
   • Keep related code together
   • Use clear file naming

4. Documentation

   • Document component usage
   • Explain integration steps
   • Provide examples

Future Enhancements

1. Analytics Integration

   • Track AI content performance
   • Monitor quality metrics
   • Analyze user engagement

2. Advanced Features

   • Inline AI contributions
   • Section-specific metadata
   • Quality assessment tools

3. User Experience

   • Interactive tooltips
   • Customizable displays
   • Accessibility improvements

Conclusion

Implementing AI metadata in Docusaurus helps maintain transparency while following best practices for theme development. The solution we've created is:

• Type-safe
• Maintainable
• Extensible
• Well-documented

You can find the complete implementation in our GitHub repository, and we welcome contributions and suggestions for improvements.