Skip to main content
ClearDocs

Documentation

Welcome to ClearDocs — a production-ready documentation platform that turns your Markdown files into a polished, searchable, and secure documentation site. Built on Next.js v16, MDX v3, and Tailwind CSS v4, ClearDocs delivers everything a modern documentation site needs: 29 purpose-built components, 26 color themes, full-text search, dark mode, password protection, SEO optimization, and AI readiness — all working together out of the box with zero configuration.

Quick Start

Get your documentation site running in under 60 seconds:

  1. Clone the repository

    Bash
    Bash
    git clone https://github.com/devops-infinity/cleardocs.git my-docs
cd my-docs

  2. Set up environment variables

    The setup script generates all required secrets (passwords, JWT keys, cookie salts) automatically. No manual configuration needed.

    Bash
    Bash
    bash scripts/setup-env.sh

  3. Install dependencies and start

    Bash
    Bash
    npm install
npm run dev

  4. Open your docs site

    Visit http://localhost:3000 to see your documentation site live. Every .mdx file you add under app/ becomes a page automatically — no routing setup, no config files, no build plugins.

What You Get

ClearDocs is a complete documentation platform. Here is everything included in your purchase, organized by what it does for you:

Content and Authoring

Write documentation in Markdown with the full power of React components embedded directly in your pages. ClearDocs supports GitHub Flavored Markdown (tables, strikethrough, task lists), six types of callout alerts, and a library of 29 custom components that handle everything from API endpoint documentation to interactive diagrams.

  • MDX Support — Write documentation in Markdown with embedded React components
  • 65+ Language Syntax Highlighting — Code blocks with language detection, line numbers, line highlighting, diff markers, word highlighting, collapsible sections, and copy-to-clipboard
  • Code Groups — Tabbed code blocks for showing the same concept in multiple languages or package managers
  • Mermaid Diagrams — 15+ diagram types (flowchart, sequence, ER, class, state, gantt, pie, gitGraph, journey, mindmap, timeline, and more) rendered directly in Markdown
  • GitHub-Style Alerts — Note, tip, important, warning, caution, and danger callouts
  • Copy Page as Markdown — One-click copy of the entire page content as Markdown or plain text for pasting into AI tools

Components

Every documentation pattern you encounter in practice — from API references to feature comparisons to release announcements — has a dedicated component in ClearDocs. Each component is responsive, keyboard-accessible, dark-mode compatible, and styled to match your chosen theme.

  • API Documentation Blocks — Styled endpoint display with color-coded method badges, headers, multi-response tabs, authentication indicators, rate limiting, deprecation notices, and auto-generated cURL examples
  • Parameter and Response Fields — Structured field documentation with type badges, location indicators, required/optional markers, and default values
  • Tabs — Content organized in tabbed panels with keyboard navigation
  • Steps — Numbered step-by-step guides with visual connectors
  • Cards — Feature showcases and navigation grids with configurable columns
  • Accordion — Collapsible FAQ sections with smooth animation
  • Badge — Inline status indicators in 5 variants (default, info, success, warning, danger)
  • File Tree — Visual directory structure display from indented text
  • Changelog — Technical release timeline with typed labels (added, fixed, changed, removed, breaking, deprecated, security)
  • Release Notes — User-facing release announcements with 8 highlight types
  • Image Zoom — Click-to-zoom lightbox for images
  • Embed — Responsive iframe embeds with URL allowlist security (YouTube, GitHub)
  • Comparison Table — Side-by-side feature comparison with 10 visual indicator types and optional column highlighting

Readers find what they need without friction. The sidebar, search, breadcrumbs, table of contents, and page navigation are all generated automatically from your file structure. There is nothing to configure — add a file and it appears in every navigation surface.

  • Auto-Generated Sidebar — Built from the file system with 3-level depth and smart name formatting for 140+ technical acronyms
  • Full-Text Search — Search across all pages with scored ranking, context snippets, and Cmd+K / Ctrl+K keyboard shortcut
  • Table of Contents — On-page scroll-spy TOC on desktop and collapsible TOC on mobile
  • Breadcrumb Navigation — Auto-formatted path breadcrumbs on every page
  • Previous/Next Navigation — Sequential page navigation at the bottom of each article

Theming and Accessibility

Make the documentation site yours. ClearDocs ships with 26 professionally designed color themes, each with coordinated light and dark modes. Switch themes with a single environment variable — no code changes, no CSS overrides, no design work required.

  • 26 Theme Variants — Choose from emerald, amber, blue, cyan, fuchsia, gray, green, indigo, lime, mauve, mist, neutral, olive, orange, pink, purple, red, rose, sky, slate, stone, taupe, teal, violet, yellow, and zinc via THEME_VARIANT environment variable
  • Dark Mode Toggle — Light, dark, and system modes with automatic detection of prefers-color-scheme and localStorage persistence
  • Responsive Design — Mobile-friendly layout with collapsible sidebar and backdrop overlay
  • Skip to Content — Keyboard-accessible skip link for screen reader users
  • Focus Management — Route-change focus management and visible focus indicators
  • Reduced Motion — Respects prefers-reduced-motion system preference
  • Print Stylesheet — Optimized rendering for printed documentation

Security

ClearDocs takes security seriously. Private mode protects your documentation behind password authentication with JWT sessions, browser fingerprinting, timing-safe password comparison, CSRF protection, and rate limiting. Nine HTTP security headers are applied to every response, and four layers of crawler blocking ensure private content stays private.

  • Password Protection — JWT sessions with 14-day expiry and browser fingerprinting
  • Secure Cookies — __Host- prefix, httpOnly, secure, sameSite: lax
  • Rate Limiting — 5 login attempts per IP with 15-minute lockout
  • 9 Security Headers — HSTS, CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, X-Robots-Tag, and more
  • Public/Private Mode — Toggle between open access and password-protected documentation via ACCESS_MODE environment variable

SEO and AI Readiness

When you run ClearDocs in public mode, every page is optimized for search engines and AI agents. Sitemaps, OpenGraph tags, canonical URLs, structured data, and AI-specific endpoints are generated automatically from your content.

  • Dynamic Sitemap — Auto-generated sitemap.xml in public mode
  • OpenGraph and Twitter Cards — Per-page social sharing meta tags with descriptions extracted from content
  • Canonical URLs — Proper <link rel="canonical"> on every page
  • JSON-LD Structured Data — TechArticle and BreadcrumbList schema.org markup
  • Dynamic robots.txt — 28+ bot rules in private mode, open crawling in public mode
  • llms.txt and llms-full.txt — Auto-generated AI agent endpoints for LLM discoverability
  • Health Check — /api/health endpoint for uptime monitoring

Pages

Getting Started (4 pages)

Total Documentation Pages: 4