Docsector Reader

Docsector Reader 📖

A documentation rendering engine built with Vue 3, Quasar v2 and Vite with AI features.

Transform Markdown content into beautiful, navigable documentation sites — with i18n, syntax highlighting, dark/light mode, and anchor navigation.

---

🤖 AI-Friendly Features

• 📋 Copy Page — One-click button copies the current page as raw Markdown, ready to paste into LLMs
• 📄 View as Markdown — Open any page as plain text by appending .md to the URL, with locale support (?lang=)
• 🧠 Markdown Negotiation — Requests with Accept: text/markdown receive markdown responses, while browsers keep HTML by default
• 🔐 Web Bot Auth Directory — Optional signed JWKS directory at /.well-known/http-message-signatures-directory for bot identity verification
• 🤖 Open in ChatGPT / Claude — One-click links to open the current page directly in ChatGPT or Claude for Q&A
• 🤖 LLM Bot Detection — Automatically serves raw Markdown to known AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Cloudflare-AI-Search, GrokBot, and others)
• 🗺️ Sitemap Generation — Automatic sitemap.xml generation at build time with root-relative URLs by default and absolute URLs when siteUrl is configured
• 🤖 AI-Friendly robots.txt — Scaffold includes a robots.txt explicitly allowing 24 AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Cloudflare-AI-Search, GrokBot, etc.), and the build appends Sitemap: /sitemap.xml at the end for crawler discovery
• 🧭 Content Signals — Optional Content-Signal directive for declaring AI usage policy (ai-train, search, ai-input) in robots.txt
• 🧩 Agent Skills Discovery Index — Optional /.well-known/agent-skills/index.json with RFC v0.2.0 schema and SHA-256 digests
• ✍️ Docsector Authoring Skill — Publishable SKILL.md that teaches agents Docsector blocks, page patterns, MCP lookup, and WebMCP tools
• 🪪 MCP Server Card — Optional /.well-known/mcp/server-card.json for MCP server discovery before connection
• 🌐 WebMCP Browser Tools — Optional registration of in-page tools via navigator.modelContext for browser agents
• 🤖 AI Assistant Panel — Optional documentation assistant drawer backed by Cloudflare AI Search through an internal same-origin endpoint
• 🗂️ API Catalog Well-Known — Auto-generates /.well-known/api-catalog as Linkset JSON for machine-readable API discovery
• 🔗 Homepage Link Headers — Auto-generated Link response headers for agent discovery (api-catalog, service-doc, service-desc, describedby) per RFC 8288 / RFC 9727
• 🔌 MCP Server — Auto-generated MCP server at /mcp for AI assistant integration (Claude Desktop, VS Code, etc.)
• 📄 llms.txt / llms-full.txt — Auto-generated llms.txt index and full-content file for LLM discovery (requires siteUrl in config)

---

✨ Features

• 📝 Markdown Rendering — Write docs in Markdown, rendered with syntax highlighting (Prism.js)
• 📋 Clickable Inline Code — Backtick-rendered inline code snippets are clickable across pages, subpages, and AI assistant answers
• 🔽 Nested Markdown Lists — Ordered and unordered lists preserve sublist hierarchy across multiple indentation levels
• ☑️ Markdown Task Lists — GitBook-style - [ ] and - [x] items render as read-only checkboxes with nested subtasks
• ⌨️ Keyboard Shortcut Keycaps — Author GitBook-style shortcuts with raw ... tags, rendered consistently across docs and AI assistant answers
• 🖼️ Block Image Captions & Zoom — Standalone Markdown images render as zoomable figures, and raw figure / picture markup supports separate alt text and captions
• 🧱 Raw HTML in Markdown — Renders inline and block HTML tags inside markdown sections (including homepage remote README content)
• 🧩 Mermaid Diagrams — Native support for fenced `mermaid blocks, with automatic dark/light theme switching
• ➗ Math & KaTeX — Native support for inline $...$ and display $$...$$ formulas rendered with KaTeX
• 🚨 GitHub-Style Alerts — Native support for [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], and [!CAUTION]
• 🌍 Internationalization (i18n) — Multi-language support with HJSON locale files and per-page translations
• 🌗 Dark/Light Mode — Automatic theme switching with Quasar Dark Plugin
• 🧰 Docsector CLI Skill Installer — Install the built-in authoring skill into older scaffolds with docsector install-skill
• 🔗 Anchor Navigation — Right-side source-ordered Table of Contents tree with stable scroll tracking, resize-safe drawer state, auto-scroll to the active section, and active-heading resolution based on the last heading that crossed the content threshold
• 🖱️ Active Menu Item UX — Active menu entries keep pointer cursor, clear URL hash without redundant navigation, and prevent accidental label text selection
• 🔎 Search — Menu search across all documentation content and tags
• 💬 Assistant Chat UX Enhancements — Long conversations keep focus on recent messages, load earlier history progressively, deduplicate repeated sources, preserve the assistant panel open state across reloads, include per-message copy actions and hover-revealed message times, and show a floating quick return to the bottom
• 📱 Responsive — Mobile-friendly with collapsible sidebar and drawers
• 🏷️ Clickable Header Branding — The configured branding.logo and branding.name render as a home link in the global header, aligned left on desktop with a compact mobile treatment
• 📚 Book Tabs with Per-State Colors — Define *.book.js tabs with icons, order, and color.active / color.inactive
• 📐 Book Layout Presets — Configure books with the default documentation chrome or a fullwidth layout that keeps the header and book tabs while removing the sidebar, subpage toolbar, and Table of Contents
• 🦶 Global Branding Footer — Built-in Powered by Docsector footer renders across documentation and system pages, while respecting each page's own scroll container for full-width layout integration without double scrollbars
• 🔀 Internal Shortcut Pages — Route entries can redirect with config.link.to, keeping localized titles while inheriting icon/status from the destination page
• 📐 Responsive Subpage Toolbar — Subpage actions align with the content column on desktop and dock to the bottom on mobile
• 🆚 Subpage Templates — Subpages opt into a structured template via vs: { template: 'vs' }; the managed/strict vs template owns the order and localized titles of its Features, Performance and Security sections (one ## heading per section, missing sections dropped gracefully), auto-colorizes ✓/✗/➕ comparison marks, and highlights the column whose header matches the consumer's branding.name
• ⬆️ Reading Progress Back to Top — Documentation subpages can show a floating back-to-top control with circular reading progress that stays above the mobile subpage toolbar
• 🏷️ Status Badges — Mark pages as done, draft, empty, or new with visual indicators
• ✏️ Edit on GitHub — Direct links to edit pages on your repository
• 🧭 Robust Edit Link Mapping — Normalizes route paths (including trailing slashes) into page.subpage.locale.md source files for reliable GitHub edit URLs
• 📅 Last Updated Date — Automatic per-page "last updated" date from git commit history, locale-formatted
• 📊 Translation Progress — Automatic translation percentage based on header coverage
• 🌐 Accurate Available Translations — Locale availability counter now uses actual localized page source presence, avoiding false negatives when metadata is equal
• 🏠 Markdown Home at Root — Homepage is rendered from src/pages/Homepage.{lang}.md directly at /
• 🧱 Configurable Homepage Layout — Set homePage.layout to default or fullwidth; fullwidth keeps the header and book tabs while removing the sidebar, subpage toolbar, Table of Contents, and homepage footer
• 🌍 Remote README as Home — Optional build-time remote README source for homepage with automatic local fallback and automatic primary-title handoff when the remote README already provides the project heading
• 🔗 GitHub-Compatible Heading Anchors — Markdown headings use GitHub-style slugs so standard README Table of Contents links work inside Docsector
• 📖 Expandable Markdown Sections — Use ... to collapse secondary content while keeping rich Markdown support inside the body
• 1️⃣ Stepper Guides — Use ` with nested ...` items to render native Quasar vertical steppers with rich Markdown and optional per-step icon overrides
• 🕒 Timeline Updates — Use ` with nested ... entries and optional ` labels to publish GitBook-inspired changelog items with direct-link anchors, tag icons/colors, and rich Markdown bodies
• 📎 File Attachment Blocks — Use ... in Markdown to render downloadable file cards with automatic local size detection and support for external URLs
• 🌐 Embedded URL Blocks — Use ... to render curated embeds for YouTube, Vimeo, Spotify, and CodePen with a safe link-card fallback for unsupported URLs
• 🧭 Quick Links Custom Element — Use ` and ` in Markdown to render rich home navigation cards
• 🗂️ Cards Custom Element — Use ` and ` in Markdown to render linked content cards with optional cover images
• 🧾 API JSON Reference Block — Use `` in Markdown to render Quasar-compatible API reference UIs from public JSON assets without inventing a new schema
• 🧠 Docsector Authoring Skill Docs — Documents the built-in SKILL.md and reference files so agents can learn Docsector blocks, page patterns, MCP lookup, and WebMCP tools from a public manual page
• 🗃️ Multi-Version History — Archive older major versions under src/pages/.old// and expose them at prefixed routes (e.g. /v0.x/guide/...) while keeping the current docs at unprefixed routes
• 🏷️ Version Selector Badges — Every version in the sidebar selector displays a color-coded badge: green for released, orange for draft, red for deprecated; fully customizable via badge: { label, color, textColor }
• 📂 Tabbed Code Blocks — Group consecutive fenced code blocks into tabs using the group and tab attributes in the fence info line
• 🧪 Live Code Example Blocks — Use `` to render bundled Vue SFC examples with a live preview, GitHub source link, source toggle, and CodePen export for compatible examples
• 🍞 Breadcrumb Path Display — Show a file path breadcrumb above code blocks with the breadcrumb attribute; renders as clickable path segments
• 🎨 File Type Icons — Automatically resolves file extension or filename to a Material Icon Theme SVG icon, shown inline in tabs and beside the last breadcrumb segment
• ⚙️ Single Config File — Customize branding, links, and languages via docsector.config.js

---

🔌 MCP Server (Model Context Protocol)

Docsector Reader can automatically generate an MCP server at /mcp during build, allowing AI assistants like Claude to search and read your documentation in real time.

Enable MCP

Add mcp to your docsector.config.js:

export default {
  // ... other config ...

  mcp: {
    serverName: 'my-docs',       // MCP server identifier
    toolSuffix: 'my_docs'        // Tool name suffix (e.g. search_my_docs)
  },

  siteUrl: 'https://my-docs.example.com'  // Required for MCP URLs
}

What the build generates

When mcp is configured, docsector build generates:

| File | Purpose | |---|---| | dist/spa/mcp-pages.json | Page index (title, path, book) for search | | functions/mcp.js | Cloudflare Pages Function implementing MCP | | dist/spa/_routes.json | Routes /mcp to the function | | dist/spa/_headers | CORS headers for MCP endpoint |

Exposed tools

| Tool | Description | |---|---| | search_{suffix} | Search documentation by keyword, returns matching pages | | get_page_{suffix} | Get full Markdown content of a specific page |

Test locally

npx docsector build
npx wrangler pages dev dist/spa

# In another terminal:
curl http://localhost:8788/mcp
curl -X POST http://localhost:8788/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Configure in AI assistants

VS Code (mcp.json):

{
  "servers": {
    "my-docs": {
      "type": "http",
      "url": "https://my-docs.example.com/mcp"
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "my-docs": {
      "type": "url",
      "url": "https://my-docs.example.com/mcp"
    }
  }
}

---

🪪 MCP Server Card Discovery

Docsector Reader can publish an MCP Server Card at:

• /.well-known/mcp/server-card.json

This supports pre-connection MCP discovery, exposing:

• serverInfo (name, version)
• MCP transport endpoint (defaults to /mcp)
• capabilities for tools/resources/prompts

When MCP is enabled, tool capabilities are derived from the generated server:

• search_{toolSuffix}
• get_page_{toolSuffix}

Configure

export default {
  // ...other config

  mcp: {
    serverName: 'my-docs',
    toolSuffix: 'my_docs'
  },

  mcpServerCard: {
    enabled: true,
    path: '/.well-known/mcp/server-card.json',
    transportEndpoint: '/mcp',
    transportType: 'streamable-http',
    protocolVersion: '2025-03-26',
    capabilities: {
      tools: { supported: true },
      resources: { supported: false },
      prompts: { supported: false }
    }
  }
}

Validate

npx docsector build
cat dist/spa/.well-known/mcp/server-card.json
cat dist/spa/_headers

External validation:

curl -X POST https://isitagentready.com/api/scan \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://YOUR-SITE.com"}'

Check checks.discovery.mcpServerCard.status equals "pass".

---

🌐 WebMCP Browser Tools

Docsector Reader can register browser-side tools for agents when navigator.modelContext is available (secure context required).

Default tools:

• docs.search_docs (bridges to MCP search_{toolSuffix})
• docs.get_page (bridges to MCP get_page_{toolSuffix})
• docs.navigate_to (SPA navigation)
• docs.copy_current_page (current page markdown URL/content)

WebMCP Configure

export default {
  // ...other config

  mcp: {
    serverName: 'my-docs',
    toolSuffix: 'my_docs'
  },

  webMcp: {
    enabled: true,
    apiMode: 'dual', // 'registerTool' | 'dual'
    toolPrefix: 'docs',
    bridgeEndpoint: '/mcp',
    bridgeToMcp: true,
    tools: {
      searchDocs: true,
      getPage: true,
      navigateTo: true,
      copyCurrentPage: true
    }
  }
}

Notes:

• apiMode: 'registerTool' uses only navigator.modelContext.registerTool().
• apiMode: 'dual' also attempts provideContext fallback when available.
• Registration happens on page load and is automatically cleaned up on unmount.

WebMCP Validate

curl -X POST https://isitagentready.com/api/scan \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://YOUR-SITE.com"}'

Check checks.discovery.webMcp.status equals "pass".

---

🤖 AI Assistant Panel

Docsector Reader can add an opt-in assistant panel for documentation Q&A. Users open it from the global header while reading pages and subpages; it is not a dedicated documentation route. The drawer posts to a same-origin Cloudflare Pages Function, and that function calls Cloudflare AI Search so secrets, rate-limit strategy, provider errors, and future auth stay server-side.

The panel is disabled by default. When enabled, desktop pages get a dedicated right-side assistant rail that can sit beside the table of contents on wide screens. Mobile uses a fullscreen dialog. Conversations restore at the l

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: docsector
• Source: docsector/docsector-reader
• License: MIT
• Homepage: https://docsector.com

Install and usage instructions live in the source repository linked above.