Skip to content

CLAUDE.md

Latest commit

 

History

History
84 lines (65 loc) · 3.01 KB

CLAUDE.md

File metadata and controls

84 lines (65 loc) · 3.01 KB

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Project Overview

This is a Docusaurus plugin that exposes documentation as raw markdown files for AI/LLM access. It's a fork of docusaurus-markdown-source-plugin by Nader Jaber (FlyNumber).

Architecture

docusaurus-plugin-ai-docs/
├── index.js                              # Main plugin (postBuild hook, sitemap generation)
├── theme/Root.js                         # React wrapper that injects dropdown into pages
├── components/MarkdownActionsDropdown/   # Dropdown UI component
│   └── index.js
├── package.json
├── README.md
└── LICENSE

Key Files

index.js - Main Plugin

  • postBuild hook: Processes all .md and .mdx files after Docusaurus build
  • cleanMarkdownForDisplay(): Converts MDX to clean markdown (strips React components, imports, JSX)
  • generateSitemap(): Creates _sitemap.md following Docusaurus sidebar hierarchy
  • parseSidebars(): Reads sidebars.ts or sidebars.js from the project
  • extractSlug(): Parses frontmatter slug for custom URL paths
  • getThemePath(): Registers the theme component

theme/Root.js - DOM Injection

  • Wraps the app and injects dropdown into article .markdown header elements
  • Uses MutationObserver to handle client-side navigation
  • Works with docs at root path (no /docs/ prefix requirement)

components/MarkdownActionsDropdown/index.js - UI Component

Dropdown with 5 options:

  1. Ask ChatGPT - Opens ChatGPT with page pre-loaded
  2. Ask Claude - Opens Claude with page pre-loaded
  3. Copy URL for AI Agent - Copies markdown URL to clipboard
  4. View as Markdown - Opens raw markdown in new tab
  5. Copy as Markdown - Copies markdown content to clipboard

Plugin Options

{
  projectName: 'My Project',  // Used in AI prompts (default: site title)
  rootDocId: 'introduction',  // Document ID for root slug "/" (default: 'introduction')
}

How It Works

  1. During postBuild, plugin reads all docs from docs/ directory
  2. MDX files are converted to clean markdown (removing imports, JSX, etc.)
  3. Files are output to build directory respecting frontmatter slug
  4. _sitemap.md is generated from sidebars.ts structure
  5. Theme component injects dropdown into each page header at runtime

Testing Changes

To test locally in a Docusaurus project:

# In the Docusaurus project
npm install ../path/to/docusaurus-plugin-ai-docs
npm run build
npm run serve

Then verify:

  • Dropdown appears on doc pages
  • .md URLs return clean markdown
  • /_sitemap.md shows correct hierarchy
  • ChatGPT/Claude links work with correct prompts

Conventions

  • Plugin uses vanilla JavaScript (no TypeScript, no build step)
  • React components use Docusaurus theme components (@theme/Layout, etc.)
  • All file operations use fs-extra for consistency
  • Icons are inline SVGs (ChatGPT from simpleicons.org, Claude from uxwing.com)