AI-Docs

A playground markdown-based wiki platform with MCP server integration for seamless documentation access through GitHub Copilot in VS Code.

Features

• 📝 Markdown Wiki: Static site generation using Docusaurus 3.x
• 🔍 Smart Search: Full-text search across all documentation
• 🏷️ Organization: Categories and tags for content organization
• 🔄 Git-Based Workflow: Edit content by pushing markdown files via git
• 🤖 MCP Integration: Access wiki articles directly in VS Code through GitHub Copilot
• 🐳 Docker Ready: One-command deployment with Docker Compose

Quick Start

Prerequisites

• Node.js 20 LTS or higher
• pnpm 8.x or higher
• Docker and Docker Compose (for containerized deployment)

Local Development

1. Clone the repository:

   git clone <repository-url>
   cd ai-docs

2. Install dependencies:

   corepack enable
   corepack prepare pnpm@latest --activate
   pnpm install

3. Start the development server:

   pnpm start

   The wiki will be available at http://localhost:3000

Docker Deployment

1. Build and run with Docker Compose:

   docker compose up --build

2. Access the wiki:

   • Wiki site: http://localhost:3000
   • MCP server: Running on configured port

Project Structure

ai-docs/
├── wiki/                     # Docusaurus wiki application
│   ├── docs/                # Markdown content (wiki pages)
│   ├── src/                 # Custom Docusaurus components
│   ├── static/              # Static assets (images, files)
│   ├── docusaurus.config.ts # Docusaurus configuration
│   ├── sidebars.ts          # Auto-generated sidebar (do not edit manually)
│   ├── generate-sidebars.js # Dynamic sidebar generator
│   ├── standardize-metadata.js # Metadata standardization tool
│   ├── fix-links.js         # Link fixing utility
│   └── package.json         # Wiki dependencies
├── mcp-server/              # MCP server for VS Code integration
│   ├── src/                 # TypeScript source code
│   └── package.json         # MCP server dependencies
├── indexer/                 # Document indexing service
│   ├── indexer.py           # Main indexer script
│   └── requirements.txt     # Python dependencies
├── embedding-service/       # Text embedding service
│   ├── server.py            # FastAPI server
│   └── requirements.txt     # Python dependencies
├── docker-compose.yml       # Multi-service orchestration
├── pnpm-workspace.yaml      # pnpm workspace configuration
└── package.json             # Root workspace scripts

Git-Based Content Workflow

AI-Docs uses a git-based workflow for all content changes. Simply edit markdown files, commit, and push - the site automatically rebuilds.

Basic Workflow

1. Clone the repository (first time only):

   git clone <repository-url>
   cd ai-docs

2. Create or edit markdown in wiki/docs/ directory:

   # Create a new guide
   touch wiki/docs/guides/my-guide.md
   
   # Or edit existing content
   vim wiki/docs/guides/existing-guide.md

3. Add required frontmatter:

   ---
   title: My New Guide
   description: A step-by-step guide for beginners
   category: Guides
   tags: [tutorial, beginner, example]
   date: 2025-11-14
   ---
   
   # My New Guide
   
   Your content here...

4. Commit and push your changes:

   git add wiki/docs/guides/my-guide.md
   git commit -m "Add guide for new feature"
   git push origin main

5. Automatic rebuild (Docker deployment only):

   • Git post-receive hook detects wiki/docs/ changes
   • Docker container automatically restarts
   • Sidebar automatically regenerates
   • Site regenerates with new content
   • Timeline: Complete within 30 seconds

6. Verify your changes:

   # Local dev: http://localhost:3000
   # Production: your-wiki-domain.com
   open http://localhost:3000

Setup Git Hook (For Production Deployments)

Enable automatic rebuilds on git push:

# Copy post-receive hook to your git repository
cp scripts/post-receive .git/hooks/post-receive

# Make it executable
chmod +x .git/hooks/post-receive

The hook triggers on any push that modifies the wiki/docs/ directory.

Content Organization

Categories (top-level sections):

• Wiki Docs - Documentation about using this wiki (installation, writing, workflow)
• Guides - How-to tutorials and step-by-step instructions
• Reference - API documentation, architecture, configuration
• Examples - Code samples and templates
• Blogs - Technical blog posts and articles
• CI/CD - Pipeline, GitOps, and deployment workflows
• Cloud - Cloud architecture and AWS patterns
• Docker - Container best practices and optimization
• Engineering - Java guidelines, SDLC processes
• Kubernetes - K8s deployment patterns and best practices
• Observability - Monitoring, logging, and tracing
• Onboarding - Engineer onboarding materials
• Security - Security best practices and guidelines
• Tech Radar - Technology adoption and recommendations

File Structure:

wiki/docs/
├── wiki-docs/            # Documentation about this wiki
│   ├── intro.md
│   ├── installation.md
│   ├── quickstart.md
│   ├── writing-markdown.md
│   ├── git-workflow.md
│   └── frontmatter-guide.md
├── guides/               # How-to guides
│   ├── mcp-setup.md
│   └── docker-deploy.md
├── reference/            # Technical reference
│   ├── architecture.md
│   └── mcp-tools.md
├── examples/             # Examples
│   ├── basic-page.md
│   └── advanced.md
├── blogs/                # Blog posts
│   ├── index.md
│   └── docker-best-practices.md
├── cicd/                 # CI/CD documentation
├── cloud/                # Cloud architecture
├── docker/               # Docker guides
├── engineering/          # Engineering practices
├── kubernetes/           # Kubernetes guides
├── observability/        # Observability guides
├── onboarding/           # Onboarding materials
├── security/             # Security documentation
└── tech-radar/           # Tech Radar

Page Templates

Use the provided template for consistent structure:

# Copy template for new page
cp wiki/docs/_templates/page-template.md wiki/docs/guides/my-new-page.md

# Edit with your content
code wiki/docs/guides/my-new-page.md

The template includes all required frontmatter fields and common content sections.

Maintenance Scripts

The wiki includes helpful maintenance scripts:

# Standardize metadata across all files
cd wiki && node standardize-metadata.js

# Fix internal links after reorganization
cd wiki && node fix-links.js

# Check for broken links
cd wiki && node check-broken-links.js

Best Practices

• Descriptive titles: Make titles searchable and clear
• One-sentence descriptions: Summarize the page purpose
• 3-5 tags per page: Use common tags consistently
• Update dates: Change date when making significant edits
• Test locally: Run pnpm start to preview before pushing
• Atomic commits: One logical change per commit
• Clear commit messages: Describe what and why

For detailed instructions, see Git Workflow Guide and Frontmatter Guide

MCP Server Integration

See MCP Setup Guide for instructions on connecting the MCP server to VS Code and GitHub Copilot.

Documentation

• Installation Guide
• Quick Start Guide
• Writing Markdown
• Git Workflow
• Frontmatter Guide
• MCP Setup Guide
• MCP Tools Reference
• Architecture Overview

Architecture

AI-Docs is a distributed system with multiple services:

Core Services

1. Docusaurus Wiki (Port 3000)

   • React-based static site generator
   • Serves human-readable documentation

2. MCP Server (Port 3001)

   • Node.js + TypeScript HTTP server
   • Provides AI-friendly API for GitHub Copilot
   • Query-only mode (stateless)

3. ChromaDB (Port 8000)

   • Vector database for semantic search
   • Stores 518 chunk embeddings (42 articles)

4. Embedding Service (Port 8001)

   • FastAPI + sentence-transformers
   • Converts text to 384-dimensional vectors
   • Model: all-MiniLM-L6-v2

5. Python Indexer (One-time job)

   • Reads markdown files
   • Generates embeddings
   • Populates ChromaDB

Data Flow

Indexing (One-time):

Markdown Files → Indexer → Embedding Service → ChromaDB

Querying (Runtime):

GitHub Copilot → MCP Server → Embedding Service → ChromaDB → Results

For detailed architecture diagrams and service interactions, see Architecture Overview.

Technology Stack

• Static Site Generator: Docusaurus 3.x
• Runtime: Node.js 20 LTS
• Package Manager: pnpm 8.x
• Language: TypeScript + Python
• MCP Protocol: Model Context Protocol
• Vector Database: ChromaDB
• ML Model: sentence-transformers
• Containerization: Docker with multi-stage builds
• Web Server: NGINX (production)

Constitution Principles

This project follows the AI-Docs Constitution:

1. Quick Start Priority: Get running in < 5 minutes with Docker
2. Simple Documentation: Example-driven with working demos
3. Minimal Dependencies: Each dependency provides significant value

Contributing

1. Create a new branch for your feature
2. Add or edit markdown files in docs/
3. Test locally with pnpm start
4. Commit and push your changes
5. The site will regenerate automatically

License

MIT