{"id":44721217,"url":"https://github.com/docsector/docsector-reader","last_synced_at":"2026-05-31T01:03:43.723Z","repository":{"id":149912379,"uuid":"134342479","full_name":"docsector/docsector-reader","owner":"docsector","description":"A documentation rendering engine built with Vue 3, Quasar v2 and Vite.","archived":false,"fork":false,"pushed_at":"2026-05-27T16:50:19.000Z","size":6829,"stargazers_count":21,"open_issues_count":6,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-27T17:12:12.881Z","etag":null,"topics":["ai","ai-friendly","ai-tools","anchor-navigation","builder","documentation","examples","guide","mcp","mcp-server","quasar","quasar-framework","quasar-play","showcase","source-code"],"latest_commit_sha":null,"homepage":"https://docsector.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/docsector.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2018-05-22T01:11:59.000Z","updated_at":"2026-05-27T16:51:00.000Z","dependencies_parsed_at":"2026-04-02T15:04:10.233Z","dependency_job_id":null,"html_url":"https://github.com/docsector/docsector-reader","commit_stats":null,"previous_names":["slowaways/quasar-documentation-pp","docsector/docsector-reader"],"tags_count":68,"template":false,"template_full_name":null,"purl":"pkg:github/docsector/docsector-reader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docsector%2Fdocsector-reader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docsector%2Fdocsector-reader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docsector%2Fdocsector-reader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docsector%2Fdocsector-reader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/docsector","download_url":"https://codeload.github.com/docsector/docsector-reader/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docsector%2Fdocsector-reader/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33715214,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-friendly","ai-tools","anchor-navigation","builder","documentation","examples","guide","mcp","mcp-server","quasar","quasar-framework","quasar-play","showcase","source-code"],"created_at":"2026-02-15T16:00:34.799Z","updated_at":"2026-05-31T01:03:43.717Z","avatar_url":"https://github.com/docsector.png","language":"JavaScript","funding_links":["https://github.com/sponsors/user'"],"categories":["Awesome Quasar [![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/sindresorhus/awesome)"],"sub_categories":["Tutorials"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/docsector.png\" alt=\"docsector-logo\" width=\"120px\" height=\"120px\"/\u003e\n\u003c/p\u003e\n\u003ch1 align=\"center\"\u003eDocsector Reader 📖\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n  \u003ci\u003eA documentation rendering engine built with Vue 3, Quasar v2 and Vite with AI features.\u003c/i\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@docsector/docsector-reader\"\u003e\n    \u003cimg alt=\"npm version\" src=\"https://img.shields.io/npm/v/@docsector/docsector-reader?color=blue\u0026label=npm\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/docsector/docsector-reader/blob/main/LICENSE.md\"\u003e\n    \u003cimg alt=\"License\" src=\"https://img.shields.io/github/license/docsector/docsector-reader\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nTransform Markdown content into beautiful, navigable documentation sites — with i18n, syntax highlighting, dark/light mode, and anchor navigation.\n\n---\n\n## 🤖 AI-Friendly Features\n\n- 📋 **Copy Page** — One-click button copies the current page as raw Markdown, ready to paste into LLMs\n- 📄 **View as Markdown** — Open any page as plain text by appending `.md` to the URL, with locale support (`?lang=`)\n- 🧠 **Markdown Negotiation** — Requests with `Accept: text/markdown` receive markdown responses, while browsers keep HTML by default\n- 🔐 **Web Bot Auth Directory** — Optional signed JWKS directory at `/.well-known/http-message-signatures-directory` for bot identity verification\n- 🤖 **Open in ChatGPT / Claude** — One-click links to open the current page directly in ChatGPT or Claude for Q\u0026A\n- 🤖 **LLM Bot Detection** — Automatically serves raw Markdown to known AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Cloudflare-AI-Search, GrokBot, and others)\n- 🗺️ **Sitemap Generation** — Automatic `sitemap.xml` generation at build time with root-relative URLs by default and absolute URLs when `siteUrl` is configured\n- 🤖 **AI-Friendly robots.txt** — Scaffold includes a `robots.txt` explicitly allowing 24 AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Cloudflare-AI-Search, GrokBot, etc.) and advertises `Sitemap: /sitemap.xml`\n- 🧭 **Content Signals** — Optional `Content-Signal` directive for declaring AI usage policy (`ai-train`, `search`, `ai-input`) in `robots.txt`\n- 🧩 **Agent Skills Discovery Index** — Optional `/.well-known/agent-skills/index.json` with RFC v0.2.0 schema and SHA-256 digests\n- ✍️ **Docsector Authoring Skill** — Publishable `SKILL.md` that teaches agents Docsector blocks, page patterns, MCP lookup, and WebMCP tools\n- 🪪 **MCP Server Card** — Optional `/.well-known/mcp/server-card.json` for MCP server discovery before connection\n- 🌐 **WebMCP Browser Tools** — Optional registration of in-page tools via `navigator.modelContext` for browser agents\n- 🤖 **AI Assistant Panel** — Optional documentation assistant drawer backed by Cloudflare AI Search through an internal same-origin endpoint\n- 🔗 **Homepage Link Headers** — Auto-generated `Link` response headers for agent discovery (`api-catalog`, `service-doc`, `service-desc`, `describedby`) per RFC 8288 / RFC 9727\n- 🔌 **MCP Server** — Auto-generated [MCP](https://modelcontextprotocol.io) server at `/mcp` for AI assistant integration (Claude Desktop, VS Code, etc.)\n- 📄 **llms.txt / llms-full.txt** — Auto-generated [llms.txt](https://llmstxt.org) index and full-content file for LLM discovery (requires `siteUrl` in config)\n\n---\n\n## ✨ Features\n\n- 📝 **Markdown Rendering** — Write docs in Markdown, rendered with syntax highlighting (Prism.js)\n- 📋 **Clickable Inline Code** — Backtick-rendered inline code snippets are clickable across pages, subpages, and AI assistant answers\n- 🔽 **Nested Markdown Lists** — Ordered and unordered lists preserve sublist hierarchy across multiple indentation levels\n- ☑️ **Markdown Task Lists** — GitBook-style `- [ ]` and `- [x]` items render as read-only checkboxes with nested subtasks\n- 🖼️ **Block Image Captions \u0026 Zoom** — Standalone Markdown images render as zoomable figures, and raw `figure` / `picture` markup supports separate alt text and captions\n- 🧱 **Raw HTML in Markdown** — Renders inline and block HTML tags inside markdown sections (including homepage remote README content)\n- 🧩 **Mermaid Diagrams** — Native support for fenced ` ```mermaid ` blocks, with automatic dark/light theme switching\n- ➗ **Math \u0026 KaTeX** — Native support for inline `$...$` and display `$$...$$` formulas rendered with KaTeX\n- 🚨 **GitHub-Style Alerts** — Native support for `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, and `[!CAUTION]`\n- 🌍 **Internationalization (i18n)** — Multi-language support with HJSON locale files and per-page translations\n- 🌗 **Dark/Light Mode** — Automatic theme switching with Quasar Dark Plugin\n- 🧰 **Docsector CLI Skill Installer** — Install the built-in authoring skill into older scaffolds with `docsector install-skill`\n- 🔗 **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\n- 🖱️ **Active Menu Item UX** — Active menu entries keep pointer cursor, clear URL hash without redundant navigation, and prevent accidental label text selection\n- 🔎 **Search** — Menu search across all documentation content and tags\n- 💬 **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 show a floating quick return to the bottom\n- 📱 **Responsive** — Mobile-friendly with collapsible sidebar and drawers\n- 📚 **Book Tabs with Per-State Colors** — Define `*.book.js` tabs with icons, order, and `color.active` / `color.inactive`\n- 🔀 **Internal Shortcut Pages** — Route entries can redirect with `config.link.to`, keeping localized titles while inheriting icon/status from the destination page\n- 📐 **Responsive Subpage Toolbar** — Subpage actions align with the content column on desktop and dock to the bottom on mobile\n- ⬆️ **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\n- 🏷️ **Status Badges** — Mark pages as `done`, `draft`, `empty`, or `new` with visual indicators\n- ✏️ **Edit on GitHub** — Direct links to edit pages on your repository\n- 🧭 **Robust Edit Link Mapping** — Normalizes route paths (including trailing slashes) into `page.subpage.locale.md` source files for reliable GitHub edit URLs\n- 📅 **Last Updated Date** — Automatic per-page \"last updated\" date from git commit history, locale-formatted\n- 📊 **Translation Progress** — Automatic translation percentage based on header coverage\n- 🌐 **Accurate Available Translations** — Locale availability counter now uses actual localized page source presence, avoiding false negatives when metadata is equal\n- 🏠 **Markdown Home at Root** — Homepage is rendered from `src/pages/Homepage.{lang}.md` directly at `/`\n- 🌍 **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\n- 🔗 **GitHub-Compatible Heading Anchors** — Markdown headings use GitHub-style slugs so standard README Table of Contents links work inside Docsector\n- 🧬 **Scaffolded Homepage Override Wiring** — New consumer projects automatically wire `virtual:docsector-homepage-override` into i18n message building\n- 📖 **Expandable Markdown Sections** — Use `\u003cd-block-expandable title=\"...\"\u003e...\u003c/d-block-expandable\u003e` to collapse secondary content while keeping rich Markdown support inside the body\n- 1️⃣ **Stepper Guides** — Use `\u003cd-block-stepper\u003e` with nested `\u003cd-block-step title=\"...\"\u003e...\u003c/d-block-step\u003e` items to render native Quasar vertical steppers with rich Markdown and optional per-step icon overrides\n- 🕒 **Timeline Updates** — Use `\u003cd-block-timeline\u003e` with nested `\u003cd-block-timeline-item date=\"...\"\u003e...\u003c/d-block-timeline-item\u003e` entries and optional `\u003cd-block-timeline-tag\u003e` labels to publish GitBook-inspired changelog items with direct-link anchors, tag icons/colors, and rich Markdown bodies\n- 📎 **File Attachment Blocks** — Use `\u003cd-block-file src=\"/files/...\"\u003e...\u003c/d-block-file\u003e` in Markdown to render downloadable file cards with automatic local size detection and support for external URLs\n- 🌐 **Embedded URL Blocks** — Use `\u003cd-block-embedded-url url=\"https://...\"\u003e...\u003c/d-block-embedded-url\u003e` to render curated embeds for YouTube, Vimeo, Spotify, and CodePen with a safe link-card fallback for unsupported URLs\n- 🧭 **Quick Links Custom Element** — Use `\u003cd-block-quick-links\u003e` and `\u003cd-block-quick-link\u003e` in Markdown to render rich home navigation cards\n- 🗂️ **Cards Custom Element** — Use `\u003cd-block-cards\u003e` and `\u003cd-block-card\u003e` in Markdown to render linked content cards with optional cover images\n- 🧾 **API JSON Reference Block** — Use `\u003cd-block-api src=\"...\" /\u003e` in Markdown to render Quasar-compatible API reference UIs from public JSON assets without inventing a new schema\n- 🗂️ **API Catalog Well-Known** — Auto-generates `/.well-known/api-catalog` as Linkset JSON for machine-readable API discovery\n- 🧠 **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\n- 🗃️ **Multi-Version History** — Archive older major versions under `src/pages/.old/\u003cversion\u003e/` and expose them at prefixed routes (e.g. `/v0.x/guide/...`) while keeping the current docs at unprefixed routes\n- 🏷️ **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 }`\n- 📂 **Tabbed Code Blocks** — Group consecutive fenced code blocks into tabs using the `group` and `tab` attributes in the fence info line\n- 🧪 **Live Code Example Blocks** — Use `\u003cd-block-code-example src=\"...\" /\u003e` to render bundled Vue SFC examples with a live preview, GitHub source link, source toggle, and CodePen export for compatible examples\n- 📏 **Accurate Source Code Line Counts** — Code example headers count visible lines correctly across LF, CRLF, and terminal newlines without inflating the total\n- 🍞 **Breadcrumb Path Display** — Show a file path breadcrumb above code blocks with the `breadcrumb` attribute; renders as clickable path segments\n- 🎨 **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\n- ⚙️ **Single Config File** — Customize branding, links, and languages via `docsector.config.js`\n\n---\n\n## 🔌 MCP Server (Model Context Protocol)\n\nDocsector Reader can automatically generate an [MCP](https://modelcontextprotocol.io) server at `/mcp` during build, allowing AI assistants like Claude to search and read your documentation in real time.\n\n### Enable MCP\n\nAdd `mcp` to your `docsector.config.js`:\n\n```javascript\nexport default {\n  // ... other config ...\n\n  mcp: {\n    serverName: 'my-docs',       // MCP server identifier\n    toolSuffix: 'my_docs'        // Tool name suffix (e.g. search_my_docs)\n  },\n\n  siteUrl: 'https://my-docs.example.com'  // Required for MCP URLs\n}\n```\n\n### What the build generates\n\nWhen `mcp` is configured, `docsector build` generates:\n\n| File | Purpose |\n|---|---|\n| `dist/spa/mcp-pages.json` | Page index (title, path, book) for search |\n| `functions/mcp.js` | Cloudflare Pages Function implementing MCP |\n| `dist/spa/_routes.json` | Routes `/mcp` to the function |\n| `dist/spa/_headers` | CORS headers for MCP endpoint |\n\n### Exposed tools\n\n| Tool | Description |\n|---|---|\n| `search_{suffix}` | Search documentation by keyword, returns matching pages |\n| `get_page_{suffix}` | Get full Markdown content of a specific page |\n\n### Test locally\n\n```bash\nnpx docsector build\nnpx wrangler pages dev dist/spa\n\n# In another terminal:\ncurl http://localhost:8788/mcp\ncurl -X POST http://localhost:8788/mcp \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}'\n```\n\n### Configure in AI assistants\n\n**VS Code** (`mcp.json`):\n```json\n{\n  \"servers\": {\n    \"my-docs\": {\n      \"type\": \"http\",\n      \"url\": \"https://my-docs.example.com/mcp\"\n    }\n  }\n}\n```\n\n**Claude Desktop** (`claude_desktop_config.json`):\n```json\n{\n  \"mcpServers\": {\n    \"my-docs\": {\n      \"type\": \"url\",\n      \"url\": \"https://my-docs.example.com/mcp\"\n    }\n  }\n}\n```\n\n---\n\n## 🪪 MCP Server Card Discovery\n\nDocsector Reader can publish an MCP Server Card at:\n\n- `/.well-known/mcp/server-card.json`\n\nThis supports pre-connection MCP discovery, exposing:\n\n- `serverInfo` (`name`, `version`)\n- MCP transport endpoint (defaults to `/mcp`)\n- `capabilities` for tools/resources/prompts\n\nWhen MCP is enabled, tool capabilities are derived from the generated server:\n\n- `search_{toolSuffix}`\n- `get_page_{toolSuffix}`\n\n### Configure\n\n```javascript\nexport default {\n  // ...other config\n\n  mcp: {\n    serverName: 'my-docs',\n    toolSuffix: 'my_docs'\n  },\n\n  mcpServerCard: {\n    enabled: true,\n    path: '/.well-known/mcp/server-card.json',\n    transportEndpoint: '/mcp',\n    transportType: 'streamable-http',\n    protocolVersion: '2025-03-26',\n    capabilities: {\n      tools: { supported: true },\n      resources: { supported: false },\n      prompts: { supported: false }\n    }\n  }\n}\n```\n\n### Validate\n\n```bash\nnpx docsector build\ncat dist/spa/.well-known/mcp/server-card.json\ncat dist/spa/_headers\n```\n\nExternal validation:\n\n```bash\ncurl -X POST https://isitagentready.com/api/scan \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"url\":\"https://YOUR-SITE.com\"}'\n```\n\nCheck `checks.discovery.mcpServerCard.status` equals `\"pass\"`.\n\n---\n\n## 🌐 WebMCP Browser Tools\n\nDocsector Reader can register browser-side tools for agents when\n`navigator.modelContext` is available (secure context required).\n\nDefault tools:\n\n- `docs.search_docs` (bridges to MCP `search_{toolSuffix}`)\n- `docs.get_page` (bridges to MCP `get_page_{toolSuffix}`)\n- `docs.navigate_to` (SPA navigation)\n- `docs.copy_current_page` (current page markdown URL/content)\n\n### WebMCP Configure\n\n```javascript\nexport default {\n  // ...other config\n\n  mcp: {\n    serverName: 'my-docs',\n    toolSuffix: 'my_docs'\n  },\n\n  webMcp: {\n    enabled: true,\n    apiMode: 'dual', // 'registerTool' | 'dual'\n    toolPrefix: 'docs',\n    bridgeEndpoint: '/mcp',\n    bridgeToMcp: true,\n    tools: {\n      searchDocs: true,\n      getPage: true,\n      navigateTo: true,\n      copyCurrentPage: true\n    }\n  }\n}\n```\n\nNotes:\n\n- `apiMode: 'registerTool'` uses only `navigator.modelContext.registerTool()`.\n- `apiMode: 'dual'` also attempts `provideContext` fallback when available.\n- Registration happens on page load and is automatically cleaned up on unmount.\n\n### WebMCP Validate\n\n```bash\ncurl -X POST https://isitagentready.com/api/scan \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"url\":\"https://YOUR-SITE.com\"}'\n```\n\nCheck `checks.discovery.webMcp.status` equals `\"pass\"`.\n\n---\n\n## 🤖 AI Assistant Panel\n\nDocsector Reader can add an opt-in assistant panel for documentation Q\u0026A. 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.\n\nThe 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 latest message, reveal earlier history progressively in long chats, deduplicate repeated source links, preserve the panel open state across page reloads, and provide per-message copy actions.\n\n### Configure\n\n```javascript\nexport default {\n  // ...other config\n\n  siteUrl: 'https://my-docs.example.com',\n\n  aiAssistant: {\n    enabled: true,\n    provider: 'aiSearch',\n    endpoint: '/assistant',\n    ui: {\n      title: 'Docs Assistant',\n      drawerWidth: 380,\n      wideBreakpoint: 1280,\n      showCitations: true,\n      suggestedPrompts: [\n        'How do I get started?',\n        'Summarize this page.',\n        'Where is the related API reference?'\n      ]\n    },\n    aiSearch: {\n      binding: 'AI_SEARCH',\n      instanceNameEnv: 'AI_SEARCH_INSTANCE_NAME',\n      accountIdEnv: 'CLOUDFLARE_ACCOUNT_ID',\n      apiTokenEnv: 'CLOUDFLARE_API_TOKEN',\n      model: '@cf/meta/llama-3.3-70b-instruct-fp8-fast',\n      retrievalType: 'hybrid',\n      maxResults: 6,\n      matchThreshold: 0.4,\n      contextExpansion: 1,\n      queryRewrite: { enabled: true },\n      reranking: { enabled: false },\n      stream: true\n    }\n  }\n}\n```\n\n### Cloudflare setup\n\nUse Cloudflare AI Search as the first provider path:\n\n- Create an AI Search instance in Cloudflare.\n- Build and deploy the Docsector site first; build output always publishes `/sitemap.xml` and adds `Sitemap: /sitemap.xml` to `robots.txt` for crawler discovery.\n- Use a Website data source. For the cleanest retrieval, point its specific sitemap to `/ai-search-sitemap.xml`; otherwise the crawler can discover `/sitemap.xml` from `robots.txt`.\n- Add metadata fields such as title, path, locale, book, version, and subpage if you want filtering later.\n- Set `AI_SEARCH_INSTANCE_NAME` as a Cloudflare Pages environment variable or local `.dev.vars` entry.\n- Bind the instance to Pages as `AI_SEARCH` when available, or set encrypted Pages secrets for `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` with AI Search run access.\n- Keep AI Search public endpoints optional; the built-in UI uses the configured internal endpoint by default.\n\n### Build output\n\nWhen enabled, `docsector build` can generate:\n\n| File | Purpose |\n|---|---|\n| `functions/assistant.js` | Cloudflare Pages Function for browser assistant requests |\n| `dist/spa/sitemap.xml` | Default crawler sitemap advertised from `robots.txt` |\n| `dist/spa/robots.txt` | Crawler policy with `Sitemap: /sitemap.xml` |\n| `dist/spa/ai-search-sitemap.xml` | Markdown-focused sitemap for AI Search crawling |\n| `dist/spa/.well-known/ai-search/manifest.json` | Source metadata for indexed documentation pages |\n| `dist/spa/_routes.json` | Routes the internal assistant endpoint to the Pages Function |\n\n### Validate\n\n```bash\nnpx docsector build\ncat dist/spa/sitemap.xml\ncat dist/spa/robots.txt\ncat dist/spa/ai-search-sitemap.xml\ncat dist/spa/.well-known/ai-search/manifest.json\nnpx wrangler pages dev dist/spa\n```\n\nWorkers AI, AI Search, and remote bindings can incur Cloudflare usage during local development.\n\n### Environment variables quick guide\n\nDocsector now ships `.env.example` so teams can standardize Cloudflare variables.\n\nUse the right place for each environment:\n\n- Cloudflare Pages production/preview: set vars in Pages settings (recommended).\n- Local `wrangler pages dev`: use `.dev.vars` for Function runtime variables.\n- Local Node-based tools: `.env` works when your runner actually loads it.\n\nMinimum variables when not using direct AI Search binding:\n\n```bash\nAI_SEARCH_INSTANCE_NAME=...\nCLOUDFLARE_ACCOUNT_ID=...\nCLOUDFLARE_API_TOKEN=...\n```\n\nIf you bind AI Search as `AI_SEARCH`, the Assistant tries binding first and uses REST fallback when binding is not available.\n\n---\n\n## � llms.txt (LLM Discovery)\n\nDocsector Reader automatically generates [llms.txt](https://llmstxt.org) files at build time when `siteUrl` is configured. `sitemap.xml` is generated even without `siteUrl`; `llms.txt` keeps the `siteUrl` requirement because it contains absolute Markdown links.\n\n| File | Purpose |\n|---|---|\n| `/llms.txt` | Markdown index of all pages with links to `.md` versions, grouped by type |\n| `/llms-full.txt` | Full documentation content concatenated in a single file for LLM context |\n\nOptionally add a `description` to your branding for a richer `llms.txt` blockquote:\n\n```javascript\nexport default {\n  branding: {\n    name: 'My Project',\n    version: 'v1.0.0',\n    description: 'A framework for building awesome things'\n  },\n  siteUrl: 'https://my-docs.example.com'\n}\n```\n\n---\n\n## 🔗 Link Headers (Agent Discovery)\n\nDocsector Reader adds homepage `Link` response headers at build time for agent discovery, following [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288) and [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727#section-3).\n\nDefault relations emitted on homepage (`/` and `/index.html`):\n\n- `rel=\"api-catalog\"` → `\u003c/.well-known/api-catalog\u003e`\n- `rel=\"service-doc\"` → `\u003c/\u003e`\n- `rel=\"service-desc\"` → `\u003c/mcp\u003e` (only when `mcp` is enabled)\n- `rel=\"describedby\"` → `\u003c/llms.txt\u003e` (only when `siteUrl` is configured, i.e. `llms.txt` is generated)\n\nGenerated in:\n\n- `dist/spa/_headers`\n- `dist/spa/.well-known/api-catalog` (Linkset JSON)\n\n### Optional configuration\n\n```javascript\nexport default {\n  // ...other config\n\n  linkHeaders: {\n    enabled: true,\n    apiCatalog: '/.well-known/api-catalog',\n    serviceDoc: '/',\n    serviceDesc: '/mcp',\n    describedBy: '/llms.txt'\n  },\n\n  apiCatalog: {\n    enabled: true,\n    path: '/.well-known/api-catalog',\n    items: [\n      '/mcp',\n      'https://api.example.com/openapi.json'\n    ]\n  }\n}\n```\n\nSet any target to `null` or `false` to disable that relation.\n\n---\n\n## 🏠 Remote README as Home\n\nYou can configure Docsector Reader to use a remote README as homepage content.\n\n- Fetch happens at build-time.\n- The same README content is used for all configured languages.\n- When the remote README resolves successfully, Docsector hides the autogenerated homepage title and uses the README's own primary heading in the rendered content.\n- If fetch fails, it falls back to local `src/pages/Homepage.{lang}.md` by default and keeps the usual autogenerated homepage title.\n- Standard GitHub-style heading links and README Table of Contents fragments keep working in the rendered homepage.\n\n### Configure\n\n```javascript\nexport default {\n  // ...other config\n\n  homePage: {\n    source: 'remote-readme',\n    remoteReadmeUrl: 'https://raw.githubusercontent.com/your-org/your-repo/main/README.md',\n    timeoutMs: 8000,\n    fallbackToLocal: true\n  }\n}\n```\n\n### Validate\n\n```bash\nnpx docsector build\ncat dist/spa/homepage.md\ncat dist/spa/homepage.en-US.md\n```\n\n---\n\n## 🔐 Web Bot Auth\n\nDocsector Reader can publish a signed Web Bot Auth directory at:\n\n- `/.well-known/http-message-signatures-directory`\n\nThis response is served by Cloudflare Pages runtime middleware and includes:\n\n- `Content-Type: application/http-message-signatures-directory+json`\n- `Signature`\n- `Signature-Input`\n\n### Configure directory publishing\n\n```javascript\nexport default {\n  // ...other config\n\n  webBotAuth: {\n    enabled: true,\n    directoryPath: '/.well-known/http-message-signatures-directory',\n    jwksEnv: 'WEB_BOT_AUTH_JWKS',\n    privateJwkEnv: 'WEB_BOT_AUTH_PRIVATE_JWK',\n    keyIdEnv: 'WEB_BOT_AUTH_KEY_ID',\n    keyId: null,\n    signatureMaxAge: 300,\n    signatureLabel: 'sig1'\n  }\n}\n```\n\nRequired runtime variables (Cloudflare Pages / Workers environment):\n\n- `WEB_BOT_AUTH_JWKS`: JSON string with a valid JWKS payload (`{ \"keys\": [...] }`)\n- `WEB_BOT_AUTH_PRIVATE_JWK`: JSON string for an Ed25519 private JWK used to sign directory responses\n- `WEB_BOT_AUTH_KEY_ID`: optional key id override (thumbprint or `kid`)\n\n### Sign outbound bot requests\n\nUse the helper export:\n\n```javascript\nimport { createWebBotAuthHeaders } from '@docsector/docsector-reader/web-bot-auth'\n\nconst signed = await createWebBotAuthHeaders({\n  url: 'https://crawltest.com/cdn-cgi/web-bot-auth',\n  privateJwk,\n  keyId: 'your-jwk-thumbprint',\n  signatureAgent: 'https://docs.example.com/.well-known/http-message-signatures-directory'\n})\n```\n\nAttach returned headers to your outbound request (`Signature-Agent`, `Signature-Input`, `Signature`).\n\n### Validate\n\n```bash\nnpx docsector build\ncat dist/spa/_headers\ncat dist/spa/.well-known/api-catalog\n```\n\nOr scan discoverability:\n\n```bash\ncurl -X POST https://isitagentready.com/api/scan \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"url\":\"https://YOUR-SITE.com\"}'\n```\n\nCheck `checks.discoverability.linkHeaders.status` equals `\"pass\"`.\n\n---\n\n## 🧭 Content Signals\n\nDocsector Reader can declare AI usage preferences in `robots.txt` via `Content-Signal`.\n\nWhen enabled, build output ensures a deterministic directive format:\n\n- `Content-Signal: ai-train=..., search=..., ai-input=...`\n\n### Configure\n\n```javascript\nexport default {\n  // ...other config\n\n  contentSignals: {\n    enabled: true,\n    aiTrain: 'yes',\n    search: 'yes',\n    aiInput: 'yes',\n    userAgent: '*',\n    applyToAllBlocks: false\n  }\n}\n```\n\nNotes:\n\n- `aiTrain`, `search`, and `aiInput` accept `yes` / `no` (or booleans).\n- Default scope is only `User-agent: *`.\n- Build patch is idempotent: repeated builds do not duplicate `Content-Signal` lines.\n- Build also keeps `Sitemap: /sitemap.xml` discoverable in `robots.txt` so crawlers can find the generated sitemap automatically.\n\n### Validate\n\n```bash\nnpx docsector build\ncat dist/spa/robots.txt\n```\n\nOptional external validation:\n\n```bash\ncurl -X POST https://isitagentready.com/api/scan \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"url\":\"https://YOUR-SITE.com\"}'\n```\n\nCheck `checks.botAccessControl.contentSignals.status` equals `\"pass\"`.\n\n---\n\n## 🧩 Agent Skills Discovery Index\n\nDocsector Reader can publish a discovery index at:\n\n- `/.well-known/agent-skills/index.json`\n\nThe generated payload follows Agent Skills Discovery RFC v0.2.0 and includes:\n\n- `$schema`\n- `skills[]` entries with `name`, `type`, `description`, `url`, `digest`\n\nThis repository publishes the built-in Docsector authoring skill at:\n\n- `/.well-known/agent-skills/docsector-documentation-authoring/SKILL.md`\n\nThe skill teaches agents Docsector Markdown authoring, all documented blocks, page/source conventions, MCP lookup, and WebMCP browser tools.\n\nFor projects scaffolded before the built-in skill existed, run:\n\n```bash\nnpx docsector install-skill\n```\n\nThe helper copies the skill into `.github/skills/` for repository-local assistants and into `public/.well-known/agent-skills/` for published discovery. Existing folders are skipped unless `--force` is passed.\n\nWhen `digest` is omitted in config, Docsector computes it automatically from the referenced local artifact and writes it as:\n\n- `sha256:{hex}`\n\n### Configure\n\n```javascript\nexport default {\n  // ...other config\n\n  agentSkills: {\n    enabled: true,\n    path: '/.well-known/agent-skills/index.json',\n    schema: 'https://schemas.agentskills.io/discovery/0.2.0/schema.json',\n    skills: [\n      {\n        name: 'docsector-documentation-authoring',\n        type: 'skill-md',\n        description: 'Author Docsector documentation with Markdown, custom blocks, MCP, and WebMCP.',\n        url: '/.well-known/agent-skills/docsector-documentation-authoring/SKILL.md'\n      }\n    ]\n  }\n}\n```\n\nNotes:\n\n- `name` must be lowercase alphanumeric plus hyphens.\n- `type` must be `skill-md` or `archive`.\n- `url` should point to a locally published artifact when auto-digest is used.\n\n### Validate\n\n```bash\nnpx docsector build\ncat dist/spa/.well-known/agent-skills/index.json\n```\n\nExternal validation:\n\n```bash\ncurl -X POST https://isitagentready.com/api/scan \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"url\":\"https://YOUR-SITE.com\"}'\n```\n\nCheck `checks.discovery.agentSkills.status` equals `\"pass\"`.\n\n---\n\n## �🚀 Quick Start\n\n### 📦 Install\n\n```bash\nnpm install @docsector/docsector-reader\n```\n\n### 🏗️ Scaffold a new project\n\n```bash\nnpx docsector init my-docs\ncd my-docs\nnpm install\n```\n\nThis creates a minimal project with `quasar.config.js`, `docsector.config.js`, `src/pages/`, `src/i18n/`, and `public/` — all powered by the docsector-reader engine.\n\n### 💻 Development\n\n```bash\nnpx docsector dev\n# or\nnpx quasar dev\n```\n\n### 🏭 Production Build\n\n```bash\nnpx docsector build\nnpx docsector serve    # Preview production build\n```\n\n---\n\n## 📐 Architecture — Library Mode\n\nDocsector Reader works as a **rendering engine**: it provides the layout, components, router, store, and boot files. Consumer projects supply only their **content** (pages, i18n, config, assets).\n\n```\n┌───────────────────────────────────────────────────────┐\n│  Consumer project (your-docs/)                        │\n│  ├── docsector.config.js   ← branding, links, langs  │\n│  ├── quasar.config.js      ← thin wrapper            │\n│  ├── src/pages/            ← Markdown + route defs    │\n│  ├── src/i18n/             ← language files + tags    │\n│  └── public/               ← logo, images, icons, files │\n│                                                       │\n│  ┌───────────────────────────────────────────────┐    │\n│  │  @docsector/docsector-reader (engine)         │    │\n│  │  ├── App.vue, router, store, boot files       │    │\n│  │  ├── DPage, DMenu, DH1–DH6, DefaultLayout    │    │\n│  │  ├── composables (useNavigator)               │    │\n│  │  └── CSS, Prism.js, QZoom                     │    │\n│  └───────────────────────────────────────────────┘    │\n└───────────────────────────────────────────────────────┘\n```\n\n### Consumer `quasar.config.js`\n\nThe consumer's Quasar config is a thin wrapper around the factory:\n\n```javascript\nimport { configure, createQuasarConfig } from '@docsector/docsector-reader/quasar-factory'\n\nexport default configure(() =\u003e {\n  return createQuasarConfig({\n    projectRoot: import.meta.dirname,\n\n    // Optional: consumer-specific boot files (resolved from src/boot/)\n    boot: ['qmediaplayer'],\n\n    // Optional: PWA manifest overrides\n    pwa: {\n      name: 'My Docs',\n      short_name: 'Docs',\n      theme_color: '#027be3'\n    },\n\n    // Optional: extra Vite plugins\n    vitePlugins: [],\n\n    // Optional: extend Vite config further\n    extendViteConf (viteConf) {\n      // custom aliases, plugins, etc.\n    }\n  })\n})\n```\n\n### How aliases work\n\n| Alias | Standalone | Consumer mode |\n|---|---|---|\n| `components` | project `src/components/` | package `src/components/` |\n| `layouts` | project `src/layouts/` | package `src/layouts/` |\n| `boot` | project `src/boot/` | package `src/boot/` |\n| `composables` | project `src/composables/` | package `src/composables/` |\n| `css` | project `src/css/` | package `src/css/` |\n| `stores` | project `src/store/` | package `src/store/` |\n| `pages` | project `src/pages/` | consumer `src/pages/` |\n| `src/i18n` | project `src/i18n/` | consumer `src/i18n/` |\n| `docsector.config.js` | project root | consumer root |\n\n---\n\n## ⚙️ Configuration (`docsector.config.js`)\n\n```javascript\nexport default {\n  branding: {\n    logo: '/images/logo/my-logo.png',\n    name: 'My Project',\n    version: 'v1.0.0',\n    versions: [\n      { id: 'v1.0.0', current: true, released: false },\n      { id: 'v0.9.0', released: true, status: 'deprecated' }\n    ]\n  },\n\n  links: {\n    github: 'https://github.com/org/repo',\n    discussions: 'https://github.com/org/repo/discussions',\n    chat: 'https://discord.gg/invite',\n    email: 'contact@example.com',\n    changelog: 'https://github.com/org/repo/releases',\n    roadmap: 'https://github.com/org/repo/blob/main/ROADMAP.md',\n    sponsor: 'https://github.com/sponsors/user',\n    explore: [\n      { label: '🌟 Related Project', url: 'https://github.com/org/related' }\n    ]\n  },\n\n  github: {\n    editBaseUrl: 'https://github.com/org/repo/edit/main/src/pages'\n  },\n\n  linkHeaders: {\n    enabled: true,\n    apiCatalog: '/.well-known/api-catalog',\n    serviceDoc: '/',\n    serviceDesc: '/mcp',\n    describedBy: '/llms.txt'\n  },\n\n  apiCatalog: {\n    enabled: true,\n    path: '/.well-known/api-catalog',\n    items: []\n  },\n\n  markdownNegotiation: {\n    enabled: true,\n    agentFallback: true\n  },\n\n  aiAssistant: {\n    enabled: false,\n    provider: 'aiSearch',\n    endpoint: '/assistant',\n    ui: {\n      title: 'Docsector Assistant',\n      drawerWidth: 380,\n      wideBreakpoint: 1280,\n      showCitations: true\n    },\n    aiSearch: {\n      binding: 'AI_SEARCH',\n      instanceNameEnv: 'AI_SEARCH_INSTANCE_NAME',\n      accountIdEnv: 'CLOUDFLARE_ACCOUNT_ID',\n      apiTokenEnv: 'CLOUDFLARE_API_TOKEN',\n      retrievalType: 'hybrid',\n      maxResults: 6,\n      stream: true\n    }\n  },\n\n  mcpServerCard: {\n    enabled: true,\n    path: '/.well-known/mcp/server-card.json',\n    transportEndpoint: '/mcp',\n    transportType: 'streamable-http',\n    protocolVersion: '2025-03-26'\n  },\n\n  contentSignals: {\n    enabled: true,\n    aiTrain: 'yes',\n    search: 'yes',\n    aiInput: 'yes',\n    userAgent: '*',\n    applyToAllBlocks: false\n  },\n\n  agentSkills: {\n    enabled: true,\n    path: '/.well-known/agent-skills/index.json',\n    schema: 'https://schemas.agentskills.io/discovery/0.2.0/schema.json',\n    skills: [\n      {\n        name: 'docsector-documentation-authoring',\n        type: 'skill-md',\n        description: 'Author Docsector documentation with Markdown, custom blocks, MCP, and WebMCP.',\n        url: '/.well-known/agent-skills/docsector-documentation-authoring/SKILL.md'\n      }\n    ]\n  },\n\n  languages: [\n    { image: '/images/flags/united-states-of-america.png', label: 'English (US)', value: 'en-US' },\n    { image: '/images/flags/brazil.png', label: 'Português (BR)', value: 'pt-BR' }\n  ],\n\n  defaultLanguage: 'en-US'\n}\n```\n\nThe current version keeps the normal unprefixed routes such as `/guide/getting-started/overview/`. Archived major versions can be placed under `src/pages/.old/\u003cversion\u003e/` with the same book/index/Markdown layout, and are exposed with a URL prefix such as `/v0.x/guide/getting-started/overview/`.\n\nEvery version shows a release badge in the selector. Released versions default to `released`; versions with `released: false` or `status: 'draft'` default to `draft`; versions with `status: 'deprecated'` or `deprecated: true` default to `deprecated` in red. Use `badge: { label, color, textColor }` when you need custom badge copy or colors.\n\n### MCP (optional)\n\n```javascript\n  // Enable MCP server at /mcp\n  mcp: {\n    serverName: 'my-project',   // Server identifier\n    toolSuffix: 'my_project'    // Tool name suffix\n  }\n```\n\n---\n\n## 🌍 Internationalization\n\n### i18n setup (`src/i18n/index.js`)\n\nConsumer projects use the `buildMessages` helper from the engine:\n\n```javascript\nimport { buildMessages } from '@docsector/docsector-reader/i18n'\nimport homePageOverride from 'virtual:docsector-homepage-override'\n\nconst langModules = import.meta.glob('./languages/*.hjson', { eager: true })\nconst currentMdModules = import.meta.glob('../pages/**/*.md', { eager: true, query: '?raw', import: 'default' })\nconst oldMdModules = import.meta.glob('../pages/.old/**/*.md', { eager: true, query: '?raw', import: 'default' })\nconst mdModules = { ...currentMdModules, ...oldMdModules }\n\nimport boot from 'pages/boot'\nimport { books, pageEntries } from 'virtual:docsector-books'\n\nexport default buildMessages({ langModules, mdModules, books, pageEntries, boot, homePageOverride })\n```\n\n\u003e `pageEntries` is the preferred source because it preserves per-book and per-version registries and avoids path collisions when books or archived versions reuse the same route key.\n\n### Language files\n\nPlace HJSON locale files in `src/i18n/languages/`:\n\n```\nsrc/i18n/languages/en-US.hjson\nsrc/i18n/languages/pt-BR.hjson\n```\n\n### Search tags (`src/pages/*.index.js`)\n\nDefine search keywords per page using `metadata.tags` in each book registry file:\n\n```javascript\nexport default {\n  '/my-section/my-page': {\n    config: {\n      icon: 'description',\n      book: 'manual',\n      status: 'done',\n      subpages: { showcase: false }\n    },\n    data: {\n      'en-US': { title: 'My Page' },\n      'pt-BR': { title: 'Minha Página' }\n    },\n    metadata: {\n      tags: {\n        'en-US': 'keyword1 keyword2 keyword3',\n        'pt-BR': 'palavra1 palavra2 palavra3'\n      }\n    }\n  }\n}\n```\n\n---\n\n## 📁 Consumer Project Structure\n\n```\nmy-docs/\n├── docsector.config.js        # Branding, links, languages\n├── quasar.config.js           # Thin wrapper using createQuasarConfig()\n├── package.json\n├── src/\n│   ├── pages/\n│   │   ├── manual.book.js     # Manual tab metadata (icon, order, active/inactive colors)\n│   │   ├── manual.index.js    # Manual page registry (routes + metadata)\n│   │   ├── guide.book.js      # Guide tab metadata (icon, order, active/inactive colors)\n│   │   ├── guide.index.js     # Guide page registry (routes + metadata)\n│   │   ├── boot.js            # Boot page data\n│   │   ├── guide/             # Guide pages (.md files)\n│   │   └── manual/\n│   │       ├── basic/         # Core UI docs exposed in the main manual nav\n│   │       ├── content/\n│   │       │   ├── blocks/    # User-facing Markdown block docs\n│   │       │   └── structures/ # User-facing page structure docs\n│   │       └── components/    # Legacy/internal engine-facing manual docs\n│   ├── i18n/\n│   │   ├── index.js           # Uses buildMessages() from engine\n│   │   └── languages/         # HJSON locale files\n│   ├── css/\n│   │   └── app.sass           # Optional overrides (imports engine CSS)\n│   └── boot/                  # Consumer-specific boot files\n│       └── qmediaplayer.js    # Example: custom Quasar extension\n└── public/\n    ├── images/logo.png        # Project logo\n    ├── flags/                 # Locale flag images\n    ├── icons/                 # PWA icons\n    └── files/                 # Downloadable attachments served as /files/...\n```\n\n  A common manual pattern is to keep core UI references under `src/pages/manual/basic/` with user-friendly page titles and focused entry pages such as Search, Branding, Version Switcher, Edit on GitHub, Translation Progress, and Previous \u0026 Next, end-user content references under `src/pages/manual/content/blocks/`, structural docs under `src/pages/manual/content/structures/`, and legacy/internal engine-specific references under `src/pages/manual/components/`.\n\n  Blocks in `src/pages/manual/content/blocks/` should normally provide both `overview` and `showcase` markdown pages, while structural topics can stay overview-only when a visual demo adds little value.\n\n---\n\n## 📚 Defining Books (Tabs)\n\nEach documentation tab is defined by a `*.book.js` file paired with a matching `*.index.js` registry.\n\n```javascript\nimport { defineBook } from '@docsector/docsector-reader'\n\nexport default defineBook({\n  id: 'guide',\n  label: 'Guide',\n  icon: 'school',\n  order: 2,\n  color: {\n    active: 'white',\n    inactive: 'secondary'\n  }\n})\n```\n\nDeclare menu search tags in each page entry under `metadata.tags`:\n\n```javascript\nexport default {\n  '/getting-started': {\n    config: {\n      icon: 'flag',\n      book: 'guide',\n      status: 'done',\n      subpages: { showcase: false }\n    },\n    data: {\n      'en-US': { title: 'Getting Started' },\n      'pt-BR': { title: 'Começando' }\n    },\n    metadata: {\n      tags: {\n        'en-US': 'install setup start begin quick project structure',\n        'pt-BR': 'instalar configurar iniciar começar rápido projeto estrutura'\n      }\n    }\n  }\n}\n```\n\nNotes:\n\n- `color.active` and `color.inactive` control the tab text color for each state.\n- Color values accept Quasar tokens (`secondary`, `red-6`), CSS variables (`--brand-color` or `var(--brand-color)`), and plain CSS colors (`white`, `#fff`, `rgb(...)`).\n- Legacy `color: 'secondary'` still works, but the object form is the recommended API.\n- Tabs are ordered by `order`.\n\n---\n\n## 📄 Adding Pages\n\n1️⃣ Register in `src/pages/manual.index.js` (or `src/pages/guide.index.js`):\n\n```javascript\nimport { definePage } from '@docsector/docsector-reader'\n\nexport default {\n  '/my-section/my-page': definePage({\n    config: {\n      icon: 'description',\n      status: 'new',         // 'done' | 'draft' | 'empty' | 'new'\n      version: 'v2.1.0',     // Optional: shown as \"New in\" / \"Novo em\"\n      menu: {\n        header: { label: '.my-section', icon: 'category' }\n      },\n      subpages: { showcase: false, vs: false }\n    },\n    data: {\n      'en-US': { title: 'My Page' },\n      'pt-BR': { title: 'Minha Página' }\n    }\n  })\n}\n```\n\nNotes:\n\n- In `manual.index.js`, route keys are relative to the `manual` book (for example `'/my-section/my-page'` becomes `/manual/my-section/my-page/...`).\n- You only need to set `config.book` when overriding the inferred book from the registry file.\n- When `showcase` or `vs` are enabled, the subpage toolbar aligns with the content width on desktop and becomes a bottom action bar on mobile.\n\n2️⃣ Create Markdown files:\n\n```\nsrc/pages/manual/my-section/my-page.overview.en-US.md\nsrc/pages/manual/my-section/my-page.overview.pt-BR.md\n```\n\n### Internal Links / Menu Shortcuts\n\nUse `config.link.to` when an entry should appear in menus but redirect immediately to another internal page.\n\n```javascript\nimport { definePage } from '@docsector/docsector-reader'\n\nexport default {\n  '/getting-started': definePage({\n    config: {\n      link: {\n        to: '/guide/getting-started/overview/'\n      }\n    },\n    data: {\n      'en-US': { title: 'Getting started' },\n      'pt-BR': { title: 'Começando' }\n    }\n  })\n}\n```\n\nNotes:\n\n- For shortcut pages, `link.to` and `data` are enough.\n- `icon` and `status` automatically fall back to the destination page when omitted.\n- Internal links redirect directly to the target route instead of rendering `overview` / `showcase` / `vs` locally.\n\n### GitHub-Style Alert Example\n\n```markdown\n\u003e [!CAUTION]\n\u003e NOTICE OF BREAKING CHANGE.\n\u003e\n\u003e As of 7.0.0, multiple breaking changes were introduced into the library.\n\u003e\n\u003e Please review the migration guide before updating.\n```\n\nSupported alert types: `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`.\nRegular blockquotes without `[!TYPE]` continue to work normally.\n\n### Code Example Blocks\n\n```html\n\u003cd-block-code-example src=\"manual/code-examples/basic-counter\" title=\"Basic counter\"\u003e\nOptional caption rendered as inline Markdown.\n\u003c/d-block-code-example\u003e\n```\n\nNotes:\n\n- Store live examples as Vue SFCs under `src/examples/**/*.vue`; for example, `src=\"manual/code-examples/basic-counter\"` resolves `src/examples/manual/code-examples/BasicCounter.vue` after kebab-case normalization.\n- Readers get a live preview, a GitHub button for the example SFC, a source button with Template / Script / Style / All tabs, and a CodePen button when the example can be exported safely.\n- Use `expanded=\"true\"` only when the source code should be visible by default.\n- CodePen export currently supports plain Vue SFCs with a template, optional style, and an Options API `export default` script. Named imports from `vue` and `quasar` are converted to browser globals.\n- Examples using `\u003cscript setup\u003e`, TypeScript scripts, or local imports still render in Docsector, but the CodePen action is disabled. Use `codepen=\"false\"` to hide it intentionally.\n\n### File Attachment Blocks\n\n```html\n\u003cd-block-file src=\"/files/manual/release-checklist.txt\" title=\"Release checklist\" size=\"1 KB\"\u003e\nDownload the example file bundled with the docs.\n\u003c/d-block-file\u003e\n```\n\nNotes:\n\n- Store small repo-tracked attachments in `public/files/` and link them with absolute paths such as `/files/manual/release-checklist.txt`.\n- `title` and `size` are optional. If `title` is omitted, the rendered card falls back to the filename from `src`.\n- The block body is rendered as an inline Markdown caption.\n- External URLs also work, so the same syntax can later point to R2 or another CDN without changing the page structure.\n\n### Embedded URL Blocks\n\n```html\n\u003cd-block-embedded-url url=\"https://www.youtube.com/watch?v=M7lc1UVf-VE\" title=\"YouTube player demo\"\u003e\nOptional caption rendered as inline Markdown.\n\u003c/d-block-embedded-url\u003e\n```\n\nNotes:\n\n- Supported providers currently include YouTube, Vimeo, Spotify, and CodePen.\n- The block preserves the original query string, so provider options such as `autoplay=1\u0026loop=1` keep working when supported by the destination service.\n- Unsupported or private URLs fall back to a safe external-link card instead of attempting a generic iframe.\n- Raw HTML remains the escape hatch when you need a provider outside the curated list or full manual iframe control.\n\n---\n\n\n## 🖥️ CLI Commands\n\n```bash\ndocsector init \u003cname\u003e          # Scaffold a new consumer project\ndocsector install-skill        # Install the built-in authoring skill\ndocsector install-skill --force # Refresh an existing installed authoring skill\ndocsector dev                  # Start dev server (port 8181)\ndocsector dev --port 3000      # Custom port\ndocsector build                # Build for production (dist/spa/)\ndocsector serve                # Serve production build\ndocsector help                 # Show help\n```\n\n---\n\n## 🔌 Exports\n\n| Import path | Export | Description |\n|---|---|---|\n| `@docsector/docsector-reader` | `createDocsector()` | Main helper for `docsector.config.js` objects |\n| `@docsector/docsector-reader` | `defineBook()` | Define `*.book.js` tab metadata with active/inactive colors |\n| `@docsector/docsector-reader` | `definePage()` | Define page registry entries, including internal shortcut pages |\n| `@docsector/docsector-reader/quasar-factory` | `createQuasarConfig()` | Config factory for consumer projects |\n| `@docsector/docsector-reader/quasar-factory` | `configure()` | No-op wrapper (avoids needing `quasar` dep) |\n| `@docsector/docsector-reader/i18n` | `buildMessages()` | Build i18n messages from globs + book/page registries |\n| `@docsector/docsector-reader/i18n` | `filter()` | Filter i18n messages by locale |\n\n---\n\n## 🛠️ Tech Stack\n\n| Technology | Purpose |\n|---|---|\n| **Vue 3** | Composition API + `\u003cscript setup\u003e` |\n| **Quasar v2** | UI framework |\n| **@quasar/app-vite** | Vite-based Quasar build |\n| **Vuex 4** | State management |\n| **vue-i18n 9** | Internationalization |\n| **markdown-it** | Markdown parsing |\n| **Prism.js** | Syntax highlighting |\n| **HJSON** | Human-friendly JSON for locale files |\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please open an issue or submit a pull request.\n\n---\n\n## 📃 License\n\nCopyright (c) Rodrigo de Araujo Vieira\n\n[MIT License](http://en.wikipedia.org/wiki/MIT_License)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocsector%2Fdocsector-reader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdocsector%2Fdocsector-reader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocsector%2Fdocsector-reader/lists"}