Introduction

ClearDocs is a complete, self-hosted documentation platform that turns Markdown files into a polished, searchable, and secure documentation site. It is built on Next.js 16, React 19, TypeScript 6, and Tailwind CSS 4 — a modern stack that delivers fast page loads, excellent developer experience, and long-term maintainability.

Whether you are documenting an API for external developers, building an internal knowledge base for your team, or publishing product guides for your customers, ClearDocs provides the structure, components, and infrastructure to do it professionally — without building anything from scratch.

What Makes ClearDocs Different

Most documentation tools force you to choose between power and simplicity. Static site generators give you control but require hours of plugin configuration. Hosted platforms handle the infrastructure but lock you into per-seat pricing and limited customization. ClearDocs gives you both: a fully featured platform that works out of the box, with full source code ownership so you can customize anything.

Zero-configuration content management. Create an .mdx file, write your content, and ClearDocs handles everything else — sidebar navigation, search indexing, breadcrumbs, table of contents, sitemap, OpenGraph metadata, and static generation. No configuration files, no manual routing, no build plugins.

Professional documentation components. 29 purpose-built components cover every pattern you encounter in technical writing: API endpoint documentation, structured parameter fields, tabbed code groups, feature comparison tables, step-by-step guides, release notes, interactive diagrams, and more.

Two modes, one codebase. A single ACCESS_MODE environment variable switches between password-protected (private) and open-access (public) documentation. The same deployment handles internal team docs, client portals, and public product documentation.

Full source code ownership. ClearDocs is a one-time purchase with an MIT license. No per-seat fees, no monthly subscriptions, no vendor lock-in. Deploy on Vercel, AWS, DigitalOcean, or your own server.

Technology Stack

ClearDocs is built on production-proven technologies trusted by thousands of engineering teams worldwide:

Next.js v16 — App Router with Turbopack for sub-second hot reload, SSR and SSG for optimal performance, and proxy middleware for authentication
React v19 — Server Components and concurrent rendering for fast initial page loads and smooth interactivity
MDX v3 — Markdown with embedded React components via next-mdx-remote, giving authors the simplicity of Markdown with the full power of React
Tailwind CSS v4 — Utility-first styling with OKLCH color space for perceptually uniform color themes across all 26 palettes
Prism.js v1.30 — Client-side syntax highlighting for 65+ programming languages with hydration-safe rendering
Mermaid v11 — Diagram rendering for 15+ diagram types with DOMPurify SVG sanitization for security
Jose v6 — JWT-based authentication with HS256 signing for secure session management
DOMPurify v3 — SVG sanitization for all diagram output, preventing XSS attacks
Lucide React v1.0 — Consistent icon library used across 29 components
TypeScript v6 — Full type safety across every source file in the project

Core Capabilities

Content Authoring

ClearDocs supports every content format you need for professional documentation:

File-based routing — Every .mdx file in app/ becomes a page automatically. The file path is the URL. No routing configuration needed.
MDX support — Write Markdown with embedded React components. 29 custom components are available in every page without imports.
GitHub Flavored Markdown — Tables, strikethrough, task lists, and autolinks via remark-gfm
GitHub-style alerts — Six alert types (note, tip, important, warning, caution, danger) for drawing reader attention to critical information
Frontmatter support — YAML metadata parsed via gray-matter for page descriptions used in SEO and search results
Internal link normalization — .mdx extensions are stripped automatically from links, so [Features](./features.mdx) and [Features](./features) both work
Copy page as Markdown — A dropdown button next to every page title copies the entire page content as Markdown or plain text, optimized for AI tool workflows like ChatGPT, Claude, or Cursor

Code and Diagrams

Technical documentation depends on clear, readable code examples and visual diagrams. ClearDocs provides best-in-class tooling for both:

Syntax highlighting — 65+ programming languages with Prism.js client-side highlighting and proper dependency ordering
45 language aliases — Common shortcuts like js, ts, py, sh, kt, rs, rb, tf, sol, and more
Line numbers — Automatic line numbering with configurable start offset
Line highlighting — Highlight specific lines with {1,3-5} syntax to draw attention to key code
Diff markers — Inline // [!code ++] and // [!code --] annotations for showing code changes without switching to diff format
Word highlighting — Highlight specific patterns with /pattern/ syntax to call out important variables or functions
File titles — Show file path headers with title="filename" metastring so readers know where code belongs
Collapsible code — Long blocks collapse with expandable and maxLines=N to keep pages scannable while preserving full examples
Code groups — Tabbed code blocks for showing the same concept in multiple languages or package managers (npm/yarn/pnpm)
Copy to clipboard — One-click code copying with visual feedback on every code block
Mermaid diagrams — 15+ diagram types including flowchart, sequence, class, state, gantt, pie, ER, gitGraph, journey, mindmap, timeline, quadrant, sankey, and more
Auto-detection — Mermaid diagrams render even without the mermaid language tag if the content starts with a recognized diagram keyword

Readers should never struggle to find information. ClearDocs generates every navigation surface automatically from your file structure:

Auto-generated sidebar — Built from the file system with 3-level depth support and active page highlighting
Smart name formatting — 140+ technical acronyms are preserved correctly (API, REST, GraphQL, MongoDB, JWT, SSO, RBAC, and more)
Full-text search — Client-side search across all pages with scored ranking and context snippets showing exactly where the match was found
Keyboard shortcut — Cmd+K or Ctrl+K opens the search modal from any page, following the ARIA combobox pattern for screen readers
Heading anchors — Auto-generated slug IDs with clickable links via rehype-slug and rehype-autolink-headings for easy deep-linking
Table of contents — Scroll-spy TOC on desktop that highlights the current section, with a collapsible panel on mobile
Breadcrumb navigation — Auto-formatted path breadcrumbs on every page for orientation within the site hierarchy
Previous/next navigation — Sequential page links at the bottom of every article for linear reading
Auto-generated index — <DynamicIndexContent /> builds a complete site map with page counts for landing pages
Category index — Directories without an index.mdx automatically generate a landing page listing all child pages

Documentation Components

ClearDocs ships with 29 custom components that cover every common documentation pattern. Each component is responsive, keyboard-accessible, and styled to match your chosen theme:

ApiBlock — REST API endpoint documentation with 5 HTTP method badges, color-coded headers, request/response bodies, multi-response tabs, auth indicators, deprecation notices, rate limiting, base URLs, and auto-generated cURL examples
ParamField — Structured parameter documentation with type, location (path, query, body, header), required/optional markers, default values, and deprecation labels
ResponseField — Structured response field documentation for API endpoints
CodeGroup — Tabbed code blocks with keyboard navigation for multi-language examples
Tabs / TabItem — General-purpose tabbed content panels with ARIA tablist pattern and localStorage sync
Steps — Numbered step-by-step guides with visual connectors for tutorials
Card / CardGrid — Feature showcase cards with configurable grid columns and optional icons
Accordion — Collapsible sections with smooth animation and URL hash deep-linking
Badge — Inline status indicators in five variants (default, info, success, warning, danger)
ComparisonTable — Side-by-side feature comparison with 10 visual indicator types and column highlighting
FileTree — Visual directory structure from indented text
ChangelogEntry / ChangelogLabel — Technical changelog timeline with 7 label types for developer audiences
ReleaseNote / ReleaseHighlight — User-facing release announcements with 8 highlight types for public "What's New" pages
ImageZoom — Click-to-zoom lightbox with keyboard and ARIA support
Embed — Responsive iframe embeds with URL allowlist (YouTube, GitHub) and sandbox security

Theming

ClearDocs ships with 26 professionally designed color themes. Each theme is a coordinated palette that generates light mode, dark mode, and component-level CSS custom properties automatically:

26 built-in palettes — emerald (default), amber, blue, cyan, fuchsia, gray, green, indigo, lime, mauve, mist, neutral, olive, orange, pink, purple, red, rose, sky, slate, stone, taupe, teal, violet, yellow, zinc
Dark mode toggle — Light, dark, and system modes with prefers-color-scheme auto-detection and localStorage persistence
CSS custom properties — All colors defined as semantic variables (--color-accent, --color-bg-primary, and more) that auto-switch between light and dark
Semantic aliases — Tailwind theme aliases (surface-*, content-*, edge-*, brand-*) handle dark mode automatically without dark: variant classes
Custom typography — Maven Pro for body text, JetBrains Mono for code with ligatures and slashed zeros

Security

ClearDocs protects private documentation with multiple layers of security:

Password protection — JWT sessions with 14-day expiry via jose library
Browser fingerprinting — Sessions are invalidated if the User-Agent or Accept-Language header changes, preventing session hijacking
Secure cookies — __Host- prefix, httpOnly, secure, sameSite: lax
Cookie name obfuscation — Cookie name derived from SHA-256 of COOKIE_SALT, making it unpredictable
Rate limiting — 5 login attempts per IP with 15-minute lockout and timing-safe password comparison to prevent brute force attacks
Origin validation — CSRF protection on all state-changing auth endpoints
9 security headers — HSTS (2-year with preload), CSP, X-Frame-Options, X-Content-Type-Options, X-XSS-Protection (disabled, superseded by CSP), Referrer-Policy, Permissions-Policy, X-Robots-Tag
4-layer crawler blocking — robots.txt, HTML meta robots, X-Robots-Tag header, and password-gated access (private mode)
Path traversal prevention — Slug validation rejects .. and leading /
DOMPurify — SVG sanitization on all Mermaid diagram output to prevent XSS

SEO and AI Readiness

In public mode, ClearDocs optimizes every page for search engines and AI agents automatically:

Dynamic sitemap — Auto-generated sitemap.xml from the navigation tree
OpenGraph and Twitter Cards — Per-page og:title, og:description, and twitter:card meta tags with descriptions extracted from MDX content
Canonical URLs — <link rel="canonical"> on every page to prevent duplicate content issues
JSON-LD structured data — TechArticle and BreadcrumbList schema.org markup on every documentation page for rich search results
Dynamic robots.txt — 28+ named bots blocked in private mode, full crawling permitted in public mode
llms.txt — Auto-generated AI agent index at /llms.txt listing all pages with URLs for LLM discoverability
llms-full.txt — Auto-generated full documentation content at /llms-full.txt for bulk AI context loading
Copy page as Markdown — Dropdown button next to every H1 title with Markdown and plain text copy options for AI tool workflows

Accessibility

ClearDocs follows WCAG guidelines to ensure documentation is usable by everyone:

Skip to content — Keyboard-accessible skip link visible on focus
Focus management — H1 focused on route change for screen reader announcement
Focus-visible indicators — Visible keyboard focus rings on all interactive elements (WCAG 2.4.7)
ARIA patterns — Combobox on search, tablist on tabs/code groups, dialog on modals, region on code blocks
Keyboard navigation — Arrow keys, Home/End, Enter/Space across search, tabs, code groups, and accordions
Focus trapping — Search modal and image zoom trap focus within the dialog
Body scroll lock — Background scroll disabled when modals are open
Reduced motion — Respects prefers-reduced-motion system preference
Print stylesheet — Optimized code rendering, hidden interactive elements
Content-visibility — content-visibility: auto on prose content for rendering performance

Public/Private Access Mode

ClearDocs supports two access modes through a single environment variable, allowing the same codebase to serve both internal and public documentation:

Private mode (default) — Password-protected access, all search engine and AI crawlers blocked, login required for every page
Public mode — Open access for all visitors, search engines allowed to index content, login page redirects to home, logout button hidden

Set via ACCESS_MODE environment variable. See the Access Mode documentation for configuration details.

Project Structure

Architecture

The following diagrams show how content flows through the ClearDocs build pipeline, how the layout system organizes navigation components, and how the security and SEO layers protect and optimize your site:

Environment Variables

All environment variables are generated automatically by the setup script. You only need to change them if you want to customize the defaults:

ACCESS_MODE — private (default) or public
APP_PASSWORD — Access password (private mode only)
JWT_SECRET — JWT signing key (private mode only)
COOKIE_SALT — Cookie name salt (private mode only)
THEME_VARIANT — Color palette (26 options, defaults to emerald)
NEXT_PUBLIC_SITE_URL — Site URL for sitemap and OG tags (optional, auto-detected on Vercel)

Run bash scripts/setup-env.sh to auto-generate all secrets, or copy .env.example as a starting point.

Quick Setup

Bash

git clone https://github.com/devops-infinity/cleardocs.git my-docs
cd my-docs
bash scripts/setup-env.sh
npm install
npm run dev

Adding Content

Create any .mdx file under app/ and it becomes a documentation page automatically:

Plain Text

app/guides/deployment.mdx  →  /guides/deployment
app/api-docs/endpoints.mdx →  /api-docs/endpoints

Directories become sidebar categories. Use numeric prefixes like 01-basics/ to control page ordering. Every new file is automatically added to the sidebar, search index, sitemap, and navigation — no configuration required.

Linting and Formatting

ClearDocs includes a complete linting and formatting pipeline to keep your content and code consistent: