### Quick start for existing projects

Source: https://mkdn.site/docs/getting-started

Install and run the tool on an existing documentation directory.

```bash
bun add -g mkdnsite
mkdnsite ./docs
```

--------------------------------

### Install and Run mkdnsite

Source: https://mkdn.site/

Install the package globally and start the server on a local directory.

```bash
bun add -g mkdnsite
mkdnsite ./content
```

--------------------------------

### Install mkdnsite via package manager

Source: https://mkdn.site/docs/getting-started

Recommended installation method for Bun or Node.js environments.

```bash
bun add -g mkdnsite
# or
npm install -g mkdnsite
```

--------------------------------

### Install and configure standalone binary

Source: https://mkdn.site/docs/getting-started

Manual installation for environments without a runtime, including macOS quarantine attribute removal.

```bash
# Example: macOS (Apple Silicon)
curl -L -o /usr/local/bin/mkdnsite https://github.com/mkdnsite/mkdnsite/releases/latest/download/mkdnsite-darwin-arm64
chmod +x /usr/local/bin/mkdnsite
```

```bash
sudo xattr -dr com.apple.quarantine /usr/local/bin/mkdnsite
```

--------------------------------

### Execute mkdnsite CLI commands

Source: https://mkdn.site/docs/elements

Commands for installing the package, starting the development server, and fetching content via curl.

```bash
# Install mkdnsite globally
bun add -g mkdnsite

# Start a dev server with watch mode
mkdnsite ./content --port 8080

# Fetch as markdown
curl -H "Accept: text/markdown" http://localhost:8080
```

--------------------------------

### Start the development server

Source: https://mkdn.site/docs/getting-started

Launch the server pointing to the directory containing Markdown files.

```bash
mkdnsite ./my-site
```

--------------------------------

### Complete Frontmatter Example

Source: https://mkdn.site/docs/frontmatter

A full example of a markdown file header containing various metadata fields.

```markdown
---
title: Building a Custom Theme
description: Step-by-step guide to creating a fully custom visual theme for mkdnsite.
order: 4
tags: [theming, css, customization]
date: 2024-03-01
updated: 2024-06-15
draft: false
---

# Building a Custom Theme

...
```

--------------------------------

### CLI Execution Examples

Source: https://mkdn.site/docs/cli

Common patterns for running the CLI with configuration files and flag overrides.

```bash
# Basic usage
mkdnsite ./content

# With config file
mkdnsite --config mysite.config.ts

# Mix config file and CLI overrides
mkdnsite --config mysite.config.ts --color-scheme dark --port 4000
```

--------------------------------

### Project configuration in JSON

Source: https://mkdn.site/docs/elements

Example package configuration file defining dependencies.

```json
{
  "name": "mkdnsite",
  "version": "0.0.1",
  "dependencies": {
    "react": "^19.0.0",
    "react-markdown": "^9.0.0"
  }
}
```

--------------------------------

### Project directory structure

Source: https://mkdn.site/docs/getting-started

Example layout of Markdown files for the site.

```text
my-site/
├── index.md          → /
├── about.md          → /about
└── docs/
    ├── index.md      → /docs
    └── api.md        → /docs/api
```

--------------------------------

### Run mkdnsite in a container

Source: https://mkdn.site/docs/docker

Starts the mkdnsite service mapping local content to the container.

```bash
docker run -p 3000:3000 -v ./content:/site nexdrew/mkdnsite
```

--------------------------------

### Start mkdnsite server

Source: https://mkdn.site/docs/mcp

Commands to launch the mkdnsite server using either HTTP or stdio transport modes.

```bash
mkdnsite ./content
# MCP endpoint: http://localhost:3000/mcp
```

```bash
mkdnsite mcp ./content
```

--------------------------------

### Run mkdnsite as an MCP server

Source: https://mkdn.site/docs/cli

Commands to start the MCP server using local directories, GitHub repositories, or configuration files.

```bash
# Local content directory
mkdnsite mcp ./content

# GitHub repository
mkdnsite mcp --github owner/repo

# GitHub repo with specific branch and subdirectory
mkdnsite mcp --github owner/repo --github-ref v2.0 --github-path docs

# Use a config file
mkdnsite mcp --config my-docs.config.ts
```

--------------------------------

### Markdown response example

Source: https://mkdn.site/docs/content-negotiation

Shows the raw Markdown output returned when requesting with the appropriate Accept header.

```bash
$ curl -H "Accept: text/markdown" http://localhost:3000/docs/getting-started

# Getting Started

## Install
...
```

--------------------------------

### Invoke MCP tools

Source: https://mkdn.site/docs/mcp

Examples of calling search and retrieval tools provided by the MCP server.

```text
search_docs("getting started")
→ [{ title: "Getting Started", slug: "/docs/getting-started", excerpt: "…", score: 0.42 }]
```

```text
get_page("/docs/configuration")
→ "# Configuration\n> Complete reference...\n\nmkdnsite is configured via..."
```

--------------------------------

### GET /llms.txt

Source: https://mkdn.site/docs/content-negotiation

Retrieves a list of all content available for AI discovery.

```APIDOC
## GET /llms.txt

### Description
Returns a list of all content on the site, intended for AI discovery and indexing.

### Method
GET

### Endpoint
/llms.txt
```

--------------------------------

### GET /

Source: https://mkdn.site/docs/content-negotiation

Retrieves content from the server. The format of the response is determined by the Accept header or the URL path.

```APIDOC
## GET /

### Description
Retrieves content from the server. By default, it returns HTML, but can be configured to return raw Markdown via the Accept header or by appending a .md suffix to the path.

### Method
GET

### Endpoint
/{path}

### Parameters
#### Query Parameters
- **Accept** (header) - Optional - Set to 'text/markdown' to receive raw Markdown content.

### Response
#### Success Response (200)
- **Content-Type** (header) - Indicates the format (text/html or text/markdown).
- **x-markdown-tokens** (header) - Estimated token count for Markdown content.
- **Content-Signal** (header) - Signals for AI training and search indexing usage.
```

--------------------------------

### Frontmatter Syntax

Source: https://mkdn.site/docs/frontmatter

The frontmatter block must be placed at the very start of the file using triple-dash delimiters.

```markdown
---
title: My Page
description: A short description of this page.
order: 2
draft: false
---

# My Page

Content starts here...
```

--------------------------------

### Access help and version information

Source: https://mkdn.site/docs/cli

Display CLI usage instructions or the current version of the tool.

```bash
mkdnsite --help     # show all flags
mkdnsite -h

mkdnsite --version  # show version
mkdnsite -v
```

--------------------------------

### Generate a blog site

Source: https://mkdn.site/docs/cli

Initializes a blog-preset site with reading time and date features enabled.

```bash
mkdnsite ./posts --preset blog --title "My Blog"
```

--------------------------------

### GET /api/search

Source: https://mkdn.site/docs/search

Queries the search index for content matching the provided query string.

```APIDOC
## GET /api/search

### Description
Queries the search index for content matching the provided query string and returns ranked results.

### Method
GET

### Endpoint
/api/search

### Parameters
#### Query Parameters
- **q** (string) - Optional - Search query
- **limit** (number) - Optional - Max results (capped at 50)

### Response
#### Success Response (200)
- **results** (array) - JSON array of SearchResult objects

#### Response Example
[
  {
    "slug": "/docs/configuration",
    "title": "Configuration",
    "description": "Complete reference for mkdnsite.config.ts",
    "excerpt": "…configure via mkdnsite.config.ts. All options…",
    "score": 0.842
  }
]
```

--------------------------------

### Apply site presets

Source: https://mkdn.site/docs/cli

Use the --preset flag to apply predefined configurations for documentation or blog layouts.

```bash
mkdnsite --preset docs ./content   # nav + TOC + prev/next links
mkdnsite --preset blog ./posts     # page title, date, reading time, prev/next
```

--------------------------------

### Serve content from GitHub

Source: https://mkdn.site/docs/cli

Commands to serve documentation directly from GitHub repositories, including support for authentication tokens and specific branches.

```bash
# Serve a public repo from main branch
mkdnsite --github owner/repo

# Serve a specific branch and subdirectory
mkdnsite --github owner/repo --github-ref develop --github-path docs

# Use a token for private repos or to avoid rate limits
mkdnsite --github myorg/private-docs --github-token ghp_xxx

# Or set the env var (no need for --github-token)
GITHUB_TOKEN=ghp_xxx mkdnsite --github myorg/private-docs
```

--------------------------------

### Build and run mkdnsite locally

Source: https://mkdn.site/docs/docker

Builds a custom image from the local directory and runs it with a specific volume mount.

```bash
docker build -t mkdnsite .
docker run -p 3000:3000 -v ./my-docs:/site mkdnsite
```

--------------------------------

### Define the DeploymentAdapter interface

Source: https://mkdn.site/docs/architecture

Implement this interface to handle environment-specific wiring and server startup logic.

```typescript
interface DeploymentAdapter {
  readonly name: string
  createContentSource: (config: MkdnSiteConfig) => ContentSource
  createRenderer: (config: MkdnSiteConfig) => Promise<MarkdownRenderer>
  start?: (
    handler: (request: Request) => Promise<Response>,
    config: MkdnSiteConfig
  ) => Promise<(() => void) | undefined>
}
```

--------------------------------

### Generate a branded documentation site

Source: https://mkdn.site/docs/cli

Configures a local documentation site with custom branding, logo, and accent colors.

```bash
mkdnsite ./content \
  --static ./static \
  --logo /logo.svg \
  --logo-text "My Project" \
  --accent "#0ea5e9" \
  --title "My Project Docs"
```

--------------------------------

### Basic CLI Usage

Source: https://mkdn.site/docs/cli

Standard syntax for invoking the mkdnsite command.

```bash
mkdnsite [directory] [options]
```

--------------------------------

### Run development commands

Source: https://mkdn.site/docs/theming

Execute specific development modes using bun scripts.

```bash
bun run dev:themed    # zen theme
bun run dev:light     # force light mode
bun run dev:dark      # force dark mode
```

--------------------------------

### Initialize mkdnsite handler in JavaScript

Source: https://mkdn.site/docs/elements

Configures the content source and renderer using the LocalAdapter to create a fetch handler.

```javascript
import { createHandler, resolveConfig } from 'mkdnsite'
import { LocalAdapter } from 'mkdnsite/adapters/local'

const config = resolveConfig({
  site: { title: 'My Docs' },
  theme: { mode: 'prose' }
})

const adapter = new LocalAdapter()
const source = adapter.createContentSource(config)
const renderer = await adapter.createRenderer(config)
const handler = createHandler({ source, renderer, config })
```

--------------------------------

### Configure logo

Source: https://mkdn.site/docs/cli

Set the site logo and display text, ensuring the logo file is located in the static directory.

```bash
mkdnsite --static ./static --logo /logo.png --logo-text "My Docs"
```

--------------------------------

### Initialize the mkdnsite handler

Source: https://mkdn.site/docs/architecture

Configure the handler using a custom source and renderer engine.

```typescript
import { createHandler, createRenderer, resolveConfig } from 'mkdnsite'

const config = resolveConfig({ site: { title: 'My Site' } })
const source = new MySource()

// createRenderer takes a RendererEngine string or RendererOptions object
const renderer = await createRenderer({
  engine: 'portable',
  syntaxTheme: 'github-light',
  syntaxThemeDark: 'github-dark',
  math: true
})

const handler = createHandler({ source, renderer, config })
```

--------------------------------

### Apply custom CSS

Source: https://mkdn.site/docs/cli

Inject custom styles or load external stylesheets to override default themes.

```bash
# Quick tweak via inline CSS
mkdnsite --custom-css ".mkdn-main { max-width: 1000px; }"

# Load a custom theme file
mkdnsite --static ./static --custom-css-url /my-theme.css

# Full replacement
mkdnsite --no-builtin-css --custom-css-url /my-complete-theme.css
```

--------------------------------

### Configure Analytics

Source: https://mkdn.site/docs/cli

Enable Google Analytics or server-side traffic logging for monitoring site usage.

```bash
# Add Google Analytics
mkdnsite --ga-measurement-id G-XXXXXXXXXX

# Debug traffic classification locally
mkdnsite --traffic-analytics --traffic-console
```

--------------------------------

### Run with GitHub source

Source: https://mkdn.site/docs/docker

Executes the container pointing to a specific GitHub repository.

```bash
docker run -p 3000:3000 nexdrew/mkdnsite --github owner/repo
```

--------------------------------

### Set markdown rendering engine

Source: https://mkdn.site/docs/cli

Select between the portable engine for full GFM support or the bun-native engine for performance.

```bash
mkdnsite --renderer bun-native   # Bun only, faster but no full GFM support
mkdnsite --renderer portable     # works everywhere, full GFM support (default)
```

--------------------------------

### Test content negotiation

Source: https://mkdn.site/docs/getting-started

Verify different response formats based on the Accept header.

```bash
curl http://localhost:3000                              # HTML (browser)
curl -H "Accept: text/markdown" http://localhost:3000   # Markdown (AI agent)
curl http://localhost:3000/docs/getting-started.md       # Markdown via .md suffix
curl http://localhost:3000/llms.txt                      # AI content index
```

--------------------------------

### Define site configuration

Source: https://mkdn.site/docs/getting-started

Create a TypeScript configuration file for persistent site settings.

```typescript
import type { MkdnSiteConfig } from 'mkdnsite'

const config: Partial<MkdnSiteConfig> = {
  site: {
    title: 'My Docs',
    description: 'Documentation for my project.'
  },
  theme: {
    colors: { accent: '#7c3aed' },
    colorsDark: { accent: '#a78bfa' }
  }
}

export default config
```

--------------------------------

### Configure OpenGraph and Twitter tags

Source: https://mkdn.site/docs/cli

Set social media meta tags for rich link previews.

```bash
mkdnsite ./content \
  --url "https://docs.example.com" \
  --og-image "https://docs.example.com/og-image.png" \
  --twitter-card summary_large_image \
  --twitter-site "@myproject"
```

--------------------------------

### Define mkdnsite.config.ts

Source: https://mkdn.site/docs/configuration

Create this file in the project root to define site metadata and theme settings.

```typescript
import type { MkdnSiteConfig } from 'mkdnsite'

const config: Partial<MkdnSiteConfig> = {
  site: {
    title: 'My Docs',
    description: 'Documentation for my project.',
    url: 'https://docs.example.com'
  },
  theme: {
    colorScheme: 'system',
    colors: {
      accent: '#7c3aed'
    }
  }
}

export default config
```

--------------------------------

### Set site metadata

Source: https://mkdn.site/docs/cli

Define the site title and base URL for absolute links.

```bash
mkdnsite --title "My Docs" --url "https://docs.example.com"
```

--------------------------------

### Configure Claude Desktop MCP

Source: https://mkdn.site/docs/mcp

JSON configuration for connecting Claude Desktop to mkdnsite via stdio or HTTP.

```json
{
  "mcpServers": {
    "my-docs": {
      "command": "mkdnsite",
      "args": ["mcp", "./path/to/content"]
    }
  }
}
```

```json
{
  "mcpServers": {
    "my-docs": {
      "url": "http://localhost:3000/mcp"
    }
  }
}
```

--------------------------------

### Configure site logo and text

Source: https://mkdn.site/docs/theming

Set the logo image path and site name text for the navigation sidebar header.

```typescript
theme: {
  logo: {
    src: '/logo.png',   // URL path (from staticDir)
    alt: 'My Project',
    width: 32,
    height: 32
  },
  logoText: 'My Project'
}
```

--------------------------------

### Configure syntax highlighting

Source: https://mkdn.site/docs/configuration

Sets the syntax highlighting engine to server-side rendering using Shiki.

```typescript
client: {
  syntaxHighlight: 'server'  // SSR highlighting via Shiki
}
```

--------------------------------

### Specify Static Assets Directory

Source: https://mkdn.site/docs/cli

Configures the directory for static assets like images and CSS.

```bash
mkdnsite ./docs --static ./public
```

--------------------------------

### Configure syntax highlighting themes

Source: https://mkdn.site/docs/theming

Define light and dark mode themes for Shiki syntax highlighting using theme configuration keys.

```typescript
theme: {
  syntaxTheme: 'github-light',
  syntaxThemeDark: 'github-dark'
}
```

--------------------------------

### Configure caching settings

Source: https://mkdn.site/docs/cli

Use these flags to enable in-memory response caching and define TTL or versioning parameters.

```bash
# Enable caching with custom TTL
mkdnsite --cache --cache-max-age 600

# Cache with stale-while-revalidate for CDN
mkdnsite --cache --cache-max-age 300 --cache-swr 60 --cache-version v1.4.1
```

--------------------------------

### Use a named configuration file

Source: https://mkdn.site/docs/cli

Runs the generator using a specific configuration file, with optional flag overrides.

```bash
# Use a project-specific config
mkdnsite --config docs.config.ts

# Override color scheme for testing
mkdnsite --config docs.config.ts --color-scheme dark
```

--------------------------------

### Configure local development server

Source: https://mkdn.site/docs/configuration

Settings for the local development server. These are ignored in edge or serverless environments.

```typescript
server: {
  port: 3000,
  hostname: '0.0.0.0'
}
```

--------------------------------

### Access MCP resources

Source: https://mkdn.site/docs/mcp

URI pattern for accessing documentation pages as MCP resources.

```text
mkdnsite://pages/{slug}
```

--------------------------------

### Configure server port

Source: https://mkdn.site/docs/cli

Set the port for the development server using the port flag.

```bash
mkdnsite -p 8080
mkdnsite --port 4000
```

--------------------------------

### Generate a performance-optimized site

Source: https://mkdn.site/docs/cli

Disables client-side JavaScript and forces a light color scheme for static output.

```bash
mkdnsite ./content \
  --no-client-js \
  --color-scheme light
```

--------------------------------

### Configure Content Negotiation

Source: https://mkdn.site/docs/cli

Disable Markdown serving and llms.txt generation for public-facing sites.

```bash
# Public site where you don't want to expose raw Markdown
mkdnsite --no-negotiate --no-llms-txt
```

--------------------------------

### Verify Content Negotiation and Endpoints

Source: https://mkdn.site/

Use curl to test how the server responds to different headers and URL suffixes.

```bash
# Browsers get HTML
curl http://localhost:3000

# AI agents get Markdown
curl -H "Accept: text/markdown" http://localhost:3000

# Any URL works with .md suffix
curl http://localhost:3000/docs/getting-started.md

# Auto-generated AI content index
curl http://localhost:3000/llms.txt
```

--------------------------------

### Configure analytics settings

Source: https://mkdn.site/docs/configuration

Set up Google Analytics 4 tracking and enable server-side traffic logging.

```typescript
analytics: {
  googleAnalytics: {
    measurementId: 'G-XXXXXXXXXX'  // GA4 measurement ID
  },
  traffic: {
    enabled: false,   // enable server-side traffic logging
    console: false    // log events as JSON lines to stdout
  }
}
```

--------------------------------

### Configure OpenGraph meta tags

Source: https://mkdn.site/docs/configuration

Sets up social sharing configuration for rich preview cards on platforms like Slack and Twitter.

```typescript
site: {
  title: 'My Docs',
  url: 'https://docs.example.com',
  og: {
    image: 'https://docs.example.com/og-image.png',
    type: 'website',
    twitterCard: 'summary_large_image',
    twitterSite: '@myproject'
  }
}
```

--------------------------------

### Configure staticDir

Source: https://mkdn.site/docs/configuration

Define the directory for static assets served at the root.

```typescript
staticDir: './static'  // serve ./static/logo.png at /logo.png
```

--------------------------------

### Configure GitHubSource

Source: https://mkdn.site/docs/architecture

Configuration object for connecting to a GitHub repository as a content source.

```typescript
github: {
  owner: 'mkdnsite',
  repo: 'mkdnsite',
  ref: 'main',           // branch, tag, or commit SHA
  path: 'content',       // subdirectory within the repo (optional)
  token: process.env.GITHUB_TOKEN  // for private repos / higher rate limits
}
```

--------------------------------

### get_nav

Source: https://mkdn.site/docs/mcp

Retrieves the full navigation tree structure.

```APIDOC
## get_nav

### Description
Get the full navigation tree structure.

### Returns
- **Object** - JSON navigation tree structure
```

--------------------------------

### Render a line chart for monthly active users

Source: https://mkdn.site/docs/examples

Displays a multi-series line chart comparing monthly active users across two years.

```json
{
  "type": "line",
  "data": {
    "labels": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
    "datasets": [
      {
        "label": "2024",
        "data": [1000, 1500, 1200, 1800, 2400, 2100]
      },
      {
        "label": "2025",
        "data": [1200, 1700, 1600, 2200, 2800, 3100]
      }
    ]
  },
  "options": {
    "plugins": {
      "title": { "display": true, "text": "Monthly Active Users" }
    }
  }
}
```

--------------------------------

### Override Configuration Values

Source: https://mkdn.site/docs/cli

Demonstrates using CLI flags to override specific settings defined in a configuration file.

```bash
# Force dark mode on a light-mode site
mkdnsite --config docs.config.ts --color-scheme dark
```

--------------------------------

### Configure with Docker Compose

Source: https://mkdn.site/docs/docker

Defines the service configuration for deployment using Docker Compose.

```yaml
services:
  docs:
    image: nexdrew/mkdnsite
    ports:
      - "3000:3000"
    volumes:
      - ./content:/site
```

--------------------------------

### Configure theme settings

Source: https://mkdn.site/docs/configuration

Global theme configuration object controlling visual presentation, color schemes, and branding.

```typescript
theme: {
  mode: 'prose',
  colorScheme: 'system',
  colors: {
    accent: '#7c3aed'
  },
  colorsDark: {
    accent: '#a78bfa'
  },
  logo: {
    src: '/logo.svg',
    alt: 'My Project'
  },
  logoText: 'My Project'
}
```

--------------------------------

### Configure Cursor MCP

Source: https://mkdn.site/docs/mcp

JSON configuration for adding the mkdnsite MCP server to Cursor.

```json
{
  "name": "my-docs",
  "url": "http://localhost:3000/mcp"
}
```

--------------------------------

### Set color scheme

Source: https://mkdn.site/docs/cli

Control the site's color scheme preference.

```bash
mkdnsite --color-scheme dark    # always dark
mkdnsite --color-scheme light   # always light
mkdnsite --color-scheme system  # follow OS (default)
```

--------------------------------

### Configure Client-side Features

Source: https://mkdn.site/docs/cli

Adjust performance and functionality by disabling specific client-side features like JavaScript, search, or theme toggles.

```bash
# Maximum performance / accessibility
mkdnsite --no-client-js

# Keep mermaid and copy but remove theme toggle
mkdnsite --no-theme-toggle

# Disable search (e.g. public-facing site without search UI)
mkdnsite --no-search
```

--------------------------------

### Configure include patterns

Source: https://mkdn.site/docs/configuration

Limit served files using glob patterns via config or CLI.

```typescript
include: ['docs/**', 'guides/**']
```

```bash
mkdnsite --include 'docs/**' --include 'guides/**'
```

--------------------------------

### Apply Configuration Preset

Source: https://mkdn.site/docs/configuration

Set a preset to apply default configurations, which can be overridden by explicit user settings.

```typescript
preset: 'blog'  // then override individual options as needed
```

--------------------------------

### Render a doughnut chart for traffic sources

Source: https://mkdn.site/docs/examples

Creates a doughnut chart representing percentage-based traffic distribution across different channels.

```json
{
  "type": "doughnut",
  "data": {
    "labels": ["Organic", "Direct", "Referral", "Social", "Email"],
    "datasets": [{
      "label": "Traffic Sources",
      "data": [42, 25, 15, 12, 6]
    }]
  },
  "options": {
    "plugins": {
      "title": { "display": true, "text": "Traffic by Source (%)" }
    }
  }
}
```

--------------------------------

### Standard HTML5 boilerplate

Source: https://mkdn.site/docs/elements

A basic HTML structure for web pages.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example</title>
</head>
<body>
  <h1>Hello, world!</h1>
</body>
</html>
```

--------------------------------

### list_pages

Source: https://mkdn.site/docs/mcp

Lists all available documentation pages.

```APIDOC
## list_pages

### Description
List all available documentation pages.

### Returns
- **Array** - List of objects containing { title, slug, description? }
```

--------------------------------

### Define Accept header quality weights

Source: https://mkdn.site/docs/content-negotiation

Specify content preferences using the Accept header with q-values to prioritize media types.

```http
Accept: text/html;q=0.9, text/markdown;q=0.8
```

--------------------------------

### Configure GitHub Content Source

Source: https://mkdn.site/docs/configuration

Define the GitHub repository settings to serve content from a remote source instead of a local directory.

```typescript
github: {
  owner: 'mkdnsite',   // GitHub user or org
  repo: 'mkdnsite',    // repository name
  ref: 'main',         // branch, tag, or commit SHA (default: 'main')
  path: 'content',     // subdirectory within the repo (optional)
  token: process.env.GITHUB_TOKEN  // for private repos or higher rate limits
}
```

--------------------------------

### Define Navigation Structure

Source: https://mkdn.site/docs/frontmatter

Represent file system structure with order and draft status to control navigation sidebar rendering.

```text
content/
  index.md                 (order: not set → 999)
  docs/
    index.md               (order: 0 → makes "Docs" section appear first)
    getting-started.md     (order: 1)
    configuration.md       (order: 2)
    advanced.md            (order: 99)
    wip-feature.md         (draft: true → hidden)
```

```text
Docs
  Getting Started
  Configuration
  Advanced
```

--------------------------------

### Configure contentDir

Source: https://mkdn.site/docs/configuration

Specify the directory containing markdown files.

```typescript
contentDir: './docs'  // serve from ./docs instead of ./content
```

--------------------------------

### Request content via curl

Source: https://mkdn.site/docs/content-negotiation

Demonstrates various ways to request HTML or Markdown content using curl, including header-based negotiation and URL suffixes.

```bash
# Browser request — gets HTML
curl http://localhost:3000

# AI agent — gets raw Markdown
curl -H "Accept: text/markdown" http://localhost:3000

# Claude Code style header — gets Markdown
curl -H "Accept: text/markdown, text/html, */*" http://localhost:3000

# Force Markdown via URL suffix (any client)
curl http://localhost:3000/docs/getting-started.md

# List all content for AI discovery
curl http://localhost:3000/llms.txt
```

--------------------------------

### Layout Field

Source: https://mkdn.site/docs/frontmatter

Configures the page layout structure.

```yaml
layout: wide
```

--------------------------------

### Configure fonts

Source: https://mkdn.site/docs/cli

Set font stacks for headings and body text, ensuring values with spaces are quoted.

```bash
mkdnsite --font-heading '"Playfair Display", serif' \
         --font-body '"Inter", sans-serif'
```

```bash
mkdnsite \
  --custom-css-url "https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap" \
  --font-body '"Inter", sans-serif'
```

--------------------------------

### Content Negotiation Logic Flowchart

Source: https://mkdn.site/docs/content-negotiation

Visual representation of the decision-making process for content delivery.

```mermaid
flowchart LR
    R[Request] --> CN{Accept header?}
    CN -->|text/markdown| MD[Raw Markdown]
    CN -->|text/html or */*| SSR[React SSR → HTML]
    CN -->|URL ends in .md| MD
    MD --> AM[AI agent / curl]
    SSR --> B[Browser]
```

--------------------------------

### Define static directory

Source: https://mkdn.site/docs/theming

Specify the directory for static assets to enable URL path resolution for images like the logo.

```typescript
staticDir: './static'
// ./static/logo.png is served at /logo.png
```

--------------------------------

### Configure content signals

Source: https://mkdn.site/docs/content-negotiation

Configuration snippet for mkdnsite.config.ts to manage AI content signals.

```typescript
negotiation: {
  contentSignals: {
    aiTrain: 'no',    // opt out of training
    search: 'yes',
    aiInput: 'yes'
  }
}
```

--------------------------------

### Generate a private site

Source: https://mkdn.site/docs/cli

Disables AI-related exposure features like llms.txt and negotiation for internal documentation.

```bash
mkdnsite ./content \
  --no-negotiate \
  --no-llms-txt \
  --title "Internal Docs"
```

--------------------------------

### Order Field

Source: https://mkdn.site/docs/frontmatter

Determines the navigation sidebar position; lower numbers appear first.

```yaml
order: 1
```

```text
order: 1  → Getting Started    (first)
order: 2  → Configuration
order: 3  → CLI Reference
...
order: 99 → (near the bottom)
```

```markdown
---
title: Reference
order: 10
---
```

--------------------------------

### Add custom CSS

Source: https://mkdn.site/docs/configuration

Inject inline CSS or link an external stylesheet to the theme.

```typescript
// Inline CSS appended after built-in styles
customCss: '.mkdn-main { max-width: 1000px; }',

// External stylesheet loaded via <link rel="stylesheet">
customCssUrl: '/my-theme.css'
```

--------------------------------

### Implement staticHandler

Source: https://mkdn.site/docs/configuration

Use a custom callback for serving static assets in non-filesystem environments like Cloudflare Workers.

```typescript
import { createHandler, resolveConfig } from 'mkdnsite'

const handler = createHandler({
  source,
  renderer,
  config,
  // Read static files from Cloudflare R2
  staticHandler: async (pathname) => {
    const key = pathname.replace(/^\//, '')
    const obj = await env.STATIC_BUCKET.get(key)
    if (obj == null) return null  // fall through to built-in serveStatic or 404
    return new Response(await obj.text(), {
      headers: { 'Content-Type': 'image/png' }
    })
  }
})
```

```typescript
const handler = createHandler({
  source: adapter.createContentSource(config),
  renderer: await adapter.createRenderer(config),
  config,
  staticHandler: adapter.createStaticHandler()  // reads from STATIC_BUCKET R2 binding
})
```

--------------------------------

### Configure theme mode

Source: https://mkdn.site/docs/theming

Set the theme mode to either 'prose' for default typography or 'components' for full custom component control.

```typescript
theme: {
  mode: 'prose'  // or 'components'
}
```

--------------------------------

### Configure llms.txt in mkdnsite.config.ts

Source: https://mkdn.site/docs/content-negotiation

Customize the llms.txt output by enabling it and defining section headings based on URL path segments.

```typescript
llmsTxt: {
  enabled: true,
  description: 'Documentation for my project.',
  sections: {
    'docs': 'API Reference',     // /docs/* pages → "## API Reference"
    'guides': 'Tutorials'        // /guides/* pages → "## Tutorials"
  }
}
```

--------------------------------

### Configure page metadata manually

Source: https://mkdn.site/docs/cli

Explicitly enable or disable metadata rendering features like titles, dates, and navigation links.

```bash
# Manual blog setup without a preset
mkdnsite ./posts \
  --page-title \
  --page-date \
  --reading-time \
  --prev-next \
  --no-nav \
  --no-toc
```

--------------------------------

### Render Math Expressions

Source: https://mkdn.site/docs/elements

Displays mathematical formulas using LaTeX syntax.

```latex
\int_{-\infty}^{\infty} e^{-x^2} \, dx = \sqrt{\pi}
```

```latex
\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}
```

```latex
\nabla \cdot \mathbf{E} = \frac{\rho}{\varepsilon_0}, \quad \nabla \times \mathbf{B} = \mu_0 \mathbf{J} + \mu_0 \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t}
```

--------------------------------

### Configure font tokens

Source: https://mkdn.site/docs/theming

Define font stacks for body, mono, and heading text within the theme configuration.

```typescript
theme: {
  fonts: {
    body: '"Inter", -apple-system, sans-serif',
    mono: '"JetBrains Mono", "Fira Code", monospace',
    heading: '"Playfair Display", Georgia, serif'
  }
}
```

--------------------------------

### Configure client-side features

Source: https://mkdn.site/docs/configuration

The master configuration object for enabling or disabling client-side JavaScript enhancements.

```typescript
client: {
  enabled: true,      // master switch
  themeToggle: true,  // light/dark toggle button
  math: true,         // KaTeX math rendering
  mermaid: true,      // Mermaid diagram rendering
  copyButton: true,   // copy-to-clipboard on code blocks
  search: true        // ⌘K search modal + /api/search endpoint
}
```

--------------------------------

### Configure site logo

Source: https://mkdn.site/docs/configuration

Define the logo source, dimensions, and text displayed in the navigation sidebar.

```typescript
logo: {
  src: '/logo.png',   // URL path (served from staticDir)
  alt: 'My Project',
  width: 32,          // pixels, default 32
  height: 32          // pixels, default 32
},
logoText: 'My Project'
```

--------------------------------

### CLI flags for MCP

Source: https://mkdn.site/docs/mcp

Command line arguments to control MCP behavior.

```bash
mkdnsite --no-mcp                     # disable MCP
mkdnsite --mcp-endpoint /api/mcp      # custom path
```

--------------------------------

### Fetch llms.txt via cURL

Source: https://mkdn.site/docs/content-negotiation

Retrieve the generated llms.txt file from a local development server.

```bash
curl http://localhost:3000/llms.txt
```

--------------------------------

### Toggle navigation and layout elements

Source: https://mkdn.site/docs/cli

Control the visibility of navigation sidebars, tables of contents, and footers.

```bash
mkdnsite --no-nav   # single-page or minimal sites
mkdnsite --no-toc   # disable TOC without disabling nav
```

--------------------------------

### Configure MCP settings

Source: https://mkdn.site/docs/mcp

Configuration object for enabling or disabling MCP and setting the endpoint path.

```typescript
mcp: {
  enabled: true,       // true (default) or false
  endpoint: '/mcp'     // URL path (default: /mcp)
}
```

--------------------------------

### Define YAML Frontmatter Metadata

Source: https://mkdn.site/docs/frontmatter

Use standard YAML syntax to define strings, numbers, booleans, arrays, and nested objects for page configuration.

```yaml
# Strings — quotes optional for simple values
title: Getting Started
title: "Getting Started"  # same thing

# Strings with special chars — quotes required
description: "Config options: all of them"

# Numbers
order: 1
port: 3000

# Booleans
draft: true
draft: false

# Arrays — inline syntax
tags: [one, two, three]

# Arrays — block syntax
tags:
  - one
  - two
  - three

# Nested objects
logo:
  src: /logo.png
  alt: My Site
```

--------------------------------

### get_page

Source: https://mkdn.site/docs/mcp

Retrieves the full markdown content of a specific documentation page.

```APIDOC
## get_page

### Description
Retrieve the full markdown content of a page by its slug.

### Parameters
- **slug** (string) - Required - Page slug (e.g., /docs/getting-started)

### Returns
- **string** - Markdown content with title and description header
```

--------------------------------

### Configure site metadata

Source: https://mkdn.site/docs/configuration

Defines the core site metadata used for SEO and site identification.

```typescript
site: {
  title: 'My Docs',
  description: 'Documentation for my project.',
  url: 'https://docs.example.com',
  lang: 'en'
}
```

--------------------------------

### Query the search API

Source: https://mkdn.site/docs/search

Use the /api/search endpoint to retrieve ranked search results.

```bash
curl "http://localhost:3000/api/search?q=configuration&limit=5"
```

--------------------------------

### Configure HTTP content negotiation

Source: https://mkdn.site/docs/configuration

Defines the negotiation object to control raw Markdown serving and AI content signals.

```typescript
negotiation: {
  enabled: true,
  includeTokenCount: true,
  contentSignals: {
    aiTrain: 'yes',
    search: 'yes',
    aiInput: 'yes'
  }
}
```

--------------------------------

### Hero Field

Source: https://mkdn.site/docs/frontmatter

Alias for hero_image; hero_image takes precedence if both are defined.

```yaml
hero: /static/hero.jpg
```

--------------------------------

### Create Portable Fetch Handler

Source: https://mkdn.site/docs/elements

Implements a fetch handler compatible with Web API standards across various runtimes.

```typescript
/**
 * Create a portable fetch handler for mkdnsite.
 *
 * This handler conforms to the Web API fetch(request): Response
 * pattern, making it compatible with Bun, Node, Deno, and edge runtimes.
 */
export function createHandler (opts: HandlerOptions): (request: Request) => Promise<Response> {
  const { source, renderer, config } = opts

  return async function handler (request: Request): Promise<Response> {
    const url = new URL(request.url)
    const pathname = decodeURIComponent(url.pathname)

    // Content negotiation
    const format = negotiateFormat(request.headers.get('Accept'))

    if (format === 'markdown') {
      const page = await source.getPage(pathname)
      if (page == null) {
        return new Response('# 404\n\nPage not found.\n', {
          status: 404,
          headers: { 'Content-Type': 'text/markdown; charset=utf-8' }
        })
      }
      return new Response(page.body, {
        status: 200,
        headers: markdownHeaders(estimateTokens(page.body), config.negotiation.contentSignals)
      })
    }

    // ... HTML rendering via React SSR
  }
}
```

--------------------------------

### POST /_refresh

Source: https://mkdn.site/docs/search

Triggers a manual rebuild of the search index.

```APIDOC
## POST /_refresh

### Description
Triggers an automatic rebuild of the search index.

### Method
POST

### Endpoint
/_refresh
```

--------------------------------

### Configure Content Security Policy

Source: https://mkdn.site/docs/configuration

Defines the CSP header settings. Use the extra* arrays to whitelist additional domains for scripts, styles, images, and other resources.

```typescript
csp: {
  enabled: true,          // default: true
  extraScriptSrc: [],     // additional script-src sources
  extraStyleSrc: [],      // additional style-src sources
  extraImgSrc: [],        // additional img-src sources
  extraConnectSrc: [],    // additional connect-src sources
  extraFontSrc: [],       // additional font-src sources
  reportUri: undefined    // CSP violation report URI
}
```

--------------------------------

### Customize Chart Configuration

Source: https://mkdn.site/docs/charts

Pass custom options like colors, legends, and titles within the chart configuration object.

```markdown
```chart
{
  "type": "line",
  "data": {
    "labels": ["Jan", "Feb", "Mar", "Apr", "May"],
    "datasets": [{
      "label": "Users",
      "data": [1000, 1500, 1200, 1800, 2400],
      "borderColor": "#6366f1",
      "backgroundColor": "#6366f133",
      "fill": true
    }]
  },
  "options": {
    "plugins": {
      "title": {
        "display": true,
        "text": "Monthly Active Users"
      }
    }
  }
}
```
```

--------------------------------

### Render Mermaid Flowchart

Source: https://mkdn.site/docs/elements

Displays a request-response flow diagram using Mermaid syntax.

```mermaid
graph LR
    A[Request] --> B{Accept Header}
    B -->|text/html| C[React SSR]
    B -->|text/markdown| D[Raw MD]
    C --> E[HTML Response]
    D --> F[MD Response]
```

--------------------------------

### Date Field

Source: https://mkdn.site/docs/frontmatter

Sets the publication date for the page.

```yaml
date: 2024-01-15
```

--------------------------------

### Configure web fonts with custom CSS URL

Source: https://mkdn.site/docs/theming

Load external web fonts by providing a Google Fonts URL alongside font definitions.

```typescript
theme: {
  customCssUrl: 'https://fonts.googleapis.com/css2?family=Inter:wght@300;400;600&family=Playfair+Display:ital,wght@0,700;1,400&display=swap',
  fonts: {
    body: '"Inter", sans-serif',
    heading: '"Playfair Display", serif'
  }
}
```

--------------------------------

### Define custom color palette

Source: https://mkdn.site/docs/theming

Override multiple color variables to create a custom site aesthetic.

```typescript
theme: {
  colors: {
    accent: '#7c3aed',
    link: '#7c3aed',
    bg: '#faf5ff',
    bgAlt: '#f3e8ff',
    border: '#e9d5ff'
  },
  colorsDark: {
    accent: '#a78bfa',
    link: '#a78bfa',
    bg: '#0c0414',
    bgAlt: '#1a0533',
    border: '#2d1b52'
  }
}
```

--------------------------------

### Configure theme fonts

Source: https://mkdn.site/docs/configuration

Specify font families for body, monospaced, and heading text elements.

```typescript
fonts: {
  body: '"Inter", sans-serif',           // --mkdn-font
  mono: '"JetBrains Mono", monospace',   // --mkdn-mono
  heading: '"Playfair Display", serif'   // --mkdn-font-heading
}
```

--------------------------------

### Access search index programmatically

Source: https://mkdn.site/docs/search

Use the mkdnsite library to build and query the search index within your own application code.

```typescript
import { createSearchIndex } from 'mkdnsite'
import { FilesystemSource } from 'mkdnsite'

const source = new FilesystemSource('./content')
const index = createSearchIndex()
await index.rebuild(source)

const results = index.search('configuration', 10)
console.log(results)
```

--------------------------------

### Hero Image Field

Source: https://mkdn.site/docs/frontmatter

Sets a full-width banner image above the page title.

```yaml
hero_image: /static/hero-banner.jpg
```

--------------------------------

### Description Field

Source: https://mkdn.site/docs/frontmatter

Sets the meta description for SEO and internal site listings.

```yaml
description: Install and run mkdnsite in under a minute.
```

--------------------------------

### Render a Bar Chart

Source: https://mkdn.site/docs/charts

Use a chart fenced code block to render a basic bar chart from a JSON configuration object.

```markdown
```chart
{
  "type": "bar",
  "data": {
    "labels": ["Q1", "Q2", "Q3", "Q4"],
    "datasets": [{
      "label": "Revenue ($K)",
      "data": [120, 200, 150, 280]
    }]
  }
}
```
```

--------------------------------

### Generic MCP endpoint

Source: https://mkdn.site/docs/mcp

The base URL for connecting any generic MCP client supporting HTTP transport.

```text
http://your-host:port/mcp
```

--------------------------------

### Render a bar chart for quarterly revenue

Source: https://mkdn.site/docs/examples

Defines a bar chart with four quarterly data points for revenue.

```json
{
  "type": "bar",
  "data": {
    "labels": ["Q1", "Q2", "Q3", "Q4"],
    "datasets": [{
      "label": "Revenue ($K)",
      "data": [120, 200, 150, 280]
    }]
  },
  "options": {
    "plugins": {
      "title": { "display": true, "text": "Quarterly Revenue" }
    }
  }
}
```

--------------------------------

### Configure accent color

Source: https://mkdn.site/docs/cli

Define the accent color for UI elements using CSS color values.

```bash
mkdnsite --accent "#7c3aed"
mkdnsite --accent "oklch(0.5 0.2 270)"
```

--------------------------------

### HTML response headers

Source: https://mkdn.site/docs/content-negotiation

Standard headers returned for HTML content requests.

```http
Content-Type: text/html; charset=utf-8
Vary: Accept
```

--------------------------------

### Filter Content with Glob Patterns

Source: https://mkdn.site/docs/cli

Uses include or exclude flags to restrict which markdown files are served, supporting picomatch glob syntax.

```bash
# Only serve files under docs/ and guides/
mkdnsite --include 'docs/**' --include 'guides/**'

# Exclude draft files and a private directory
mkdnsite --exclude '**/*.draft.md' --exclude 'private/**'
```

--------------------------------

### Implement a custom ContentSource

Source: https://mkdn.site/docs/architecture

Define a class implementing the ContentSource interface to integrate external data sources like APIs or CMS.

```typescript
import type { ContentSource, ContentPage, NavNode } from 'mkdnsite'

class MySource implements ContentSource {
  async getPage(slug: string): Promise<ContentPage | null> {
    // fetch from your API, database, CMS, etc.
  }

  async getNavTree(): Promise<NavNode> {
    // build navigation tree
  }

  async listPages(): Promise<ContentPage[]> {
    // return all pages for llms.txt, sitemaps, etc.
  }

  async refresh(): Promise<void> {
    // invalidate caches
  }
}
```

--------------------------------

### Apply custom CSS and fonts

Source: https://mkdn.site/docs/theming

Use custom CSS files and font definitions to significantly alter the site's visual style while maintaining the base layout.

```typescript
theme: {
  builtinCss: true,   // keep the base layout
  customCssUrl: '/zen-theme.css',
  fonts: {
    heading: '"Playfair Display", serif',
    body: '"Source Sans 3", sans-serif'
  },
  colors: {
    accent: '#b5851a',
    bg: '#faf6ee',
    preBg: '#f5f0e6'
  },
  colorsDark: {
    accent: '#d4a82a',
    bg: '#17120b',
    preBg: '#0c0904'
  }
}
```

--------------------------------

### Configure Response Caching

Source: https://mkdn.site/docs/configuration

Sets response caching and CDN header behavior. Disabled by default; requires explicit enabling.

```typescript
cache: {
  enabled: false,              // opt-in
  maxAge: 300,                 // Cache-Control max-age for HTML (seconds)
  maxAgeMarkdown: 300,         // Cache-Control max-age for markdown
  staleWhileRevalidate: 0,     // stale-while-revalidate (0 = omitted)
  versionTag: undefined        // version tag for ETag / cache busting
}
```

--------------------------------

### Trigger index refresh

Source: https://mkdn.site/docs/search

Manually trigger a rebuild of the search index by sending a POST request to the /_refresh endpoint.

```bash
curl -X POST http://localhost:3000/_refresh
```

--------------------------------

### Apply inline custom CSS

Source: https://mkdn.site/docs/theming

Inject small CSS tweaks synchronously to prevent flashes of unstyled content.

```typescript
theme: {
  customCss: `
    .mkdn-main { max-width: 1000px; }
    .mkdn-prose h1 { color: var(--mkdn-accent); }
  `
}
```

--------------------------------

### Configure color scheme

Source: https://mkdn.site/docs/theming

Define the color scheme behavior, supporting system-based switching or forced light/dark modes.

```typescript
theme: {
  colorScheme: 'system'  // 'system' | 'light' | 'dark'
}
```

--------------------------------

### Load external stylesheet

Source: https://mkdn.site/docs/theming

Reference an external CSS file to be loaded in the document head.

```typescript
theme: {
  customCssUrl: '/my-theme.css'
}
```

--------------------------------

### Custom Fields

Source: https://mkdn.site/docs/frontmatter

Additional fields are accessible via the meta object in custom components.

```yaml
---
title: API Reference
author: Jane Smith
version: 2.0
badge: stable
---
```

--------------------------------

### Request Processing Flow

Source: https://mkdn.site/docs/content-negotiation

A high-level representation of the request handling logic based on the Accept header.

```text
Request → read Accept header → decide format → return response
```