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.

— Damian Conway