Features

This page is a live demonstration of every feature available in ClearDocs. Each section below shows a real, working example of a component or capability — the same ones you will use when building your own documentation. Use this page as both a reference guide and a visual catalog of what ClearDocs can do.

Every page in ClearDocs includes a Copy page dropdown button next to the title, allowing readers to export content as Markdown or plain text with a single click.

Code Blocks

ClearDocs renders code blocks with syntax highlighting for 65+ programming languages. Every code block includes line numbers, a language badge, and a copy-to-clipboard button — all enabled by default with no configuration.

JavaScript

async function fetchDocumentation(slug) {
  const response = await fetch(`/api/docs/${slug}`)
  const data = await response.json()
  return data.content
}

TypeScript

interface DocumentPage {
  title: string
  slug: string
  content: string
  lastUpdated: Date
}
 
function formatPage(page: DocumentPage): string {
  return `# ${page.title}\n\n${page.content}`
}

Python

from pathlib import Path
 
def build_navigation(docs_dir: str) -> list[dict]:
    pages = []
    for mdx_file in Path(docs_dir).rglob("*.mdx"):
        pages.append({
            "name": mdx_file.stem.replace("-", " ").title(),
            "path": str(mdx_file.relative_to(docs_dir)),
        })
    return sorted(pages, key=lambda p: p["path"])

Bash

npm install
npm run dev
npm run build
npm run format:check

JSON

{
  "name": "cleardocs",
  "version": "1.0.0",
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build --turbopack"
  }
}

Line Highlighting

Draw attention to specific lines of code using the {1,3-5} syntax after the language identifier. Highlighted lines receive a distinct background color, making it easy to point readers to the most important parts of a code example.

interface User {
  id: string
  name: string
  email: string
  role: 'admin' | 'user'
}

Line Numbers

Line numbers are enabled by default on all code blocks. Add showLineNumbers explicitly or showLineNumbers=N to start numbering from a specific line — useful when showing a snippet from the middle of a larger file.

import { cache } from 'react'
import { readFile } from 'fs/promises'
 
const getCachedContent = cache(async (slug: string) => {
  const filePath = `./content/${slug}.mdx`
  return readFile(filePath, 'utf-8')
})
 
export default async function DocPage({ params }) {
  const content = await getCachedContent(params.slug)
  return <MDXRemote source={content} />
}

File Title

Show a file path header above any code block with title="filename". This tells readers exactly which file the code belongs to — essential for tutorials and guides where code spans multiple files.

import { SignJWT, jwtVerify } from 'jose'
 
const secret = new TextEncoder().encode(process.env.JWT_SECRET)
 
export async function createSession(payload: Record<string, unknown>) {
  return new SignJWT(payload)
    .setProtectedHeader({ alg: 'HS256' })
    .setExpirationTime('7d')
    .sign(secret)
}

Diff Highlighting

Show code changes inline with // [!code ++] and // [!code --] markers. Added lines appear with a green background and removed lines with a red background. The markers themselves are stripped from the rendered output, keeping the code clean and readable.

function getConfig() {
  return {
    theme: 'light', 
    theme: 'dark', 
    debug: true, 
    debug: false, 
  }
}

Code Groups

The Code Group component organizes multiple code blocks into a tabbed interface. This is ideal for showing the same command across different package managers, or the same logic implemented in different languages. Readers pick their preferred tab and the selection persists.

npm install next react react-dom

yarn add next react react-dom

pnpm add next react react-dom

Word Highlighting

Highlight every occurrence of a specific word or pattern using the /pattern/ syntax. This is useful for calling out variable names, function calls, or important identifiers within a code example.

interface DocumentPage {
  title: string
  slug: string
}
 
function renderPage(page: DocumentPage): string {
  return `# ${page.title}`
}

Collapsible Code

Long code blocks can overwhelm a page. The expandable metastring collapses the block to a configurable number of visible lines with an expand button. Readers see the beginning of the code and can expand to view the rest when they need it.

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [{ "name": "next" }],
    "paths": { "@/*": ["./*"] }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules"]
}

GitHub-Style Alerts

Alerts are callout blocks that draw reader attention to important information. ClearDocs supports all six GitHub alert types, each with a distinct color and icon to convey the right level of urgency.

ℹ️ NOTE Notes highlight information that users should take into account, even when skimming.

💡 TIP Tips provide optional information to help users be more successful.

📝 IMPORTANT Important information that users need to know to achieve their goal.

⚠️ WARNING Urgent information that needs immediate attention to avoid problems.

⚡ CAUTION Advises about risks or negative outcomes of certain actions.

Tabs

The Tabs component organizes content into tabbed panels. Use it to present alternative approaches, framework-specific instructions, or any content where readers need to choose between options. Tab selections can be synced across pages using the syncKey prop, so a reader who picks "React" on one page sees "React" selected on every other page.

Steps

The Steps component turns an ordered list into a visual step-by-step guide with numbered circles and vertical connectors. This is the standard format for tutorials, onboarding flows, and installation instructions — it makes sequential tasks easy to follow and visually distinct from regular content.

Cards

Cards provide a grid-based layout for feature showcases, quick navigation, and content overviews. Each card can include a title, description, optional icon, and optional link. The grid is responsive — it stacks on mobile and expands to your chosen column count on larger screens.

Accordion

The Accordion component creates collapsible content sections — ideal for FAQs, troubleshooting guides, and any content where readers benefit from progressive disclosure. Accordions support smooth animation, URL hash deep-linking (so you can link directly to a specific open accordion), and independent open/close state.

Badge

Badges are inline status indicators for labeling features, versions, and lifecycle stages. Five color variants communicate different states at a glance.

Parameter Fields

The ParamField component provides structured documentation for API parameters. Each field displays the parameter name, data type, location (path, query, body, header), required/optional status, and default value in a consistent, scannable format.

Response Fields

The ResponseField component documents the shape of API response bodies. Each field shows the name, data type, and whether the field is always present (required) or conditionally included. Nested objects are documented using dot notation.

File Tree

The FileTree component renders a visual directory structure from indented text. Use it to show project layouts, folder hierarchies, and file organization without screenshots that go stale.

Changelog

The Changelog component provides a timeline-based layout for tracking technical changes across releases. Each entry supports seven label types (added, fixed, changed, removed, breaking, deprecated, security) with color-coded badges. This format is designed for developer audiences who need a complete, detailed record of every change.

Release Notes

Release Notes are designed for end-user audiences. While the Changelog above provides a complete technical record of every change, Release Notes highlight only the changes that matter to your users — written in benefit-focused language with a card-based layout that communicates the value of each update.

Mermaid Diagrams

Mermaid diagrams are written in standard Markdown code fences and rendered as interactive SVG graphics directly on the page. ClearDocs supports 15+ diagram types — from flowcharts and sequence diagrams to gantt charts and mindmaps. All diagram output is sanitized through DOMPurify for security.

Tables

Standard Markdown tables render with responsive horizontal scrolling on narrow viewports, alternating row backgrounds for readability, and header alignment support.

Comparison Table

The Comparison Table component lets you create side-by-side feature comparisons using 10 visual indicator types. Use it to compare your product against competitors, compare pricing tiers, or compare technology options. The highlight prop visually emphasizes your recommended column.

The 10 indicator types available for comparison table cells are:

• check — included (green checkmark)
• cross — not available (red X)
• partial — limited support (amber minus)
• info — informational note (blue info)
• star — premium/paid feature (purple star)
• clock — coming soon (gray clock)
• plus — available as add-on (teal plus)
• lock — enterprise/restricted (gray lock)
• sparkle — new/beta feature (violet sparkles)
• zap — upgrade tier (amber zap)
• Any other string renders as plain text.

Use the highlight prop (column index) to visually emphasize a recommended option with a brand-tinted column and "Recommended" label.

Inline Code

Use backticks for inline code like npm run dev or next.config.mjs. Variable names like searchIndex and file paths like app/globals.css are also rendered with inline code styling.

Links

• Internal links: Introduction
• External links: Next.js Documentation

Text Formatting

Standard Markdown formatting is fully supported:

• Bold text for emphasis
• Italic text for subtle emphasis
• Strikethrough for deprecated content
• Bold and italic combined

Lists

Ordered List

1. Clone the repository
2. Install dependencies
3. Run the setup script
4. Start the development server

Unordered List

• Supports nested lists
  • Second level
    • Third level
• Back to first level

Task List

• Set up Next.js with MDX
• Add syntax highlighting (65+ languages)
• Implement global search with Cmd+K
• Add Mermaid diagram support (15+ types)
• Add API documentation blocks with multi-response tabs
• Line highlighting, diff markers, and word highlighting
• Code groups and tabbed code blocks
• Tabs, Steps, Cards, Accordion, Badge
• ParamField and ResponseField components
• Table of Contents with scroll-spy
• Dark mode toggle with system auto-detection
• 26 theme variants via environment variable
• Copy page as Markdown/Plain Text button
• Sitemap, OpenGraph, JSON-LD, canonical URLs
• llms.txt and llms-full.txt for AI agents
• Image zoom lightbox
• Embed component with URL allowlist
• Changelog and Release Notes components
• Health check endpoint
• Add versioning support
• Add i18n support

API Documentation Blocks

The ApiBlock component renders interactive REST API endpoint documentation with color-coded method badges, request/response JSON with syntax highlighting, authentication indicators, and auto-generated cURL examples. It is the centerpiece component for API reference documentation.

Blockquotes

Documentation is a love letter that you write to your future self.

Math Typesetting

ClearDocs renders LaTeX-style math equations inline and as centered blocks through remark-math and rehype-katex. KaTeX produces accessible HTML at build time — no client-side parsing, no runtime layout shift.

Inline math: the mass-energy equivalence formula is $E = mc^2$, and the Pythagorean theorem reads $a^2 + b^2 = c^2$.

Block math:

Use a single $ pair for inline equations and $$ on their own lines for block equations.

MDX Snippets

The <Snippet> component embeds reusable content fragments from the top-level snippets/ directory. Author shared blocks once — auth headers, install steps, legal notices — and reference them anywhere.

The block below is rendered live from snippets/install-note.mdx:

ℹ️ NOTE This is a reusable snippet from snippets/install-note.mdx. Edit the file once and every page that embeds it picks up the change.

npm install @your-org/sdk

Snippets share the full MDX component palette and inherit the same variable substitution context as regular pages.

Variable Substitution

Build-time {{vars.x}} placeholders resolve from cleardocs.config.json or NEXT_PUBLIC_DOCS_VAR_* environment variables. Authors write the token once and ClearDocs substitutes the configured value at render time.

This site is configured with apiUrl, supportEmail, version, and brand. Author tokens like the example below and ClearDocs substitutes the configured value at render time:

Welcome to {{vars.brand}} version {{vars.version}}. The API base URL is
`{{vars.apiUrl}}`. For support, email {{vars.supportEmail}}.

The rendered output reads: "Welcome to ClearDocs version 1.0.0. The API base URL is https://api.example.com. For support, email support@example.com."

To define your own variables, edit cleardocs.config.json at the project root. Prefix any environment variable with NEXT_PUBLIC_DOCS_VAR_ to inject deployment-specific values (env vars override the config file).

Page Meta Bar

Every MDX page can declare optional YAML frontmatter that drives a compact meta bar below the title — reading time (auto-calculated), lifecycle status (draft, beta, stable, deprecated, archived), and difficulty level (beginner, intermediate, advanced). This page itself sets:

---
status: stable
level: beginner
related:
  - /getting-started/introduction
  - /getting-started/api-reference
---

Scroll back to the top of this page to see the meta bar in action. To hide the bar on a specific page, set hideMeta: true in frontmatter.

Page Metadata Footer

Below every page ClearDocs renders a footer showing the last-updated timestamp from git log, the most recent contributors, and an "Edit on GitHub" link when NEXT_PUBLIC_REPO_URL is set. The footer is data-driven — no manual maintenance required as the documentation evolves.

Related Pages

Frontmatter related: ['/path/a', '/path/b'] renders a card grid of curated next steps below the article body. Entries are resolved against the navigation tree, so broken links never reach the rendered output. Look for the "Related pages" grid at the bottom of this page; it is populated by the frontmatter shown in the Page Meta Bar section above.

Heading Anchor Copy Buttons

Hover any heading on this page (or focus it via keyboard) to reveal a small copy icon. Clicking it copies a deep-link URL like https://example.com/getting-started/features#math-typesetting to your clipboard and updates the address bar fragment without a navigation. This turns every heading into a shareable bookmark.

Per-Page AI Deeplinks

The dropdown next to the Copy page button at the top of every page includes one-click deeplinks for ChatGPT, Claude, Perplexity, and Cursor. Each deeplink opens the AI tool with a pre-filled prompt referencing the current page URL — readers go from "I am stuck" to "ask an LLM" in one click.

Smart 404 with Suggestions

When a reader lands on a missing path, ClearDocs runs the requested slug against the static search index using Fuse.js fuzzy matching and surfaces the top five most likely intended pages. Try visiting a non-existent path like /this-page-does-not-exist to see the suggestion list in action.

Dynamic Open Graph Images

Every page exposes a 1200×630 PNG generated on demand by the /og route handler using Next.js's built-in next/og. Social platforms (X, Slack, LinkedIn, Discord) automatically pick up the image from the page's OpenGraph metadata. To preview the image directly, visit /og?title=Hello&breadcrumb=Demo.

Announcement Bar

A site-wide dismissible announcement bar can be activated by setting NEXT_PUBLIC_ANNOUNCEMENT_ID, NEXT_PUBLIC_ANNOUNCEMENT_MESSAGE, and optionally NEXT_PUBLIC_ANNOUNCEMENT_HREF plus NEXT_PUBLIC_ANNOUNCEMENT_LINK_LABEL in your environment. Dismissals persist per announcement ID via localStorage, so changing the ID re-shows the bar to every reader.

MCP Server

ClearDocs ships a built-in Model Context Protocol server at /api/mcp that exposes search_docs and fetch_page tools to AI clients (Claude Desktop, Cursor, Windsurf). The endpoint speaks JSON-RPC 2.0 over stateless HTTP and is gated by MCP_BEARER_TOKEN in private mode. See the MCP server reference for client configuration.

— Damian Conway