@docsector/docsector-reader 4.5.2 → 4.5.4

package/README.md

@@ -27,7 +27,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🤖 **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 advertises `Sitemap: /sitemap.xml`
+- 🤖 **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
@@ -46,6 +46,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 📋 **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 `<kbd>...</kbd>` 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
@@ -77,6 +78,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🌍 **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
 - 🧬 **Scaffolded Homepage Override Wiring** — New consumer projects automatically wire `virtual:docsector-homepage-override` into i18n message building
+- 🧰 **Scaffolded Dev Reliability** — New consumer projects protect Docsector virtual registries and Markdown CommonJS plugins from Vite optimizer edge cases during dev and build
 - 📖 **Expandable Markdown Sections** — Use `<d-block-expandable title="...">...</d-block-expandable>` to collapse secondary content while keeping rich Markdown support inside the body
 - 1️⃣ **Stepper Guides** — Use `<d-block-stepper>` with nested `<d-block-step title="...">...</d-block-step>` items to render native Quasar vertical steppers with rich Markdown and optional per-step icon overrides
 - 🕒 **Timeline Updates** — Use `<d-block-timeline>` with nested `<d-block-timeline-item date="...">...</d-block-timeline-item>` entries and optional `<d-block-timeline-tag>` labels to publish GitBook-inspired changelog items with direct-link anchors, tag icons/colors, and rich Markdown bodies
@@ -350,8 +352,8 @@ export default {
 Use Cloudflare AI Search as the first provider path:
 
 - Create an AI Search instance in Cloudflare.
-- Build and deploy the Docsector site first; build output always publishes `/sitemap.xml` and adds `Sitemap: /sitemap.xml` to `robots.txt` for crawler discovery.
-- 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`.
+- Build and deploy the Docsector site first; build output always publishes `/sitemap.xml` and appends `Sitemap: /sitemap.xml` to the end of `robots.txt` for crawler discovery.
+- Use a Website data source. For the cleanest retrieval, point its specific sitemap to `/ai-search-sitemap.xml`. Docsector keeps that Markdown-focused sitemap available for explicit AI Search configuration, but does not auto-announce it from `robots.txt` so Cloudflare does not index the same content twice alongside `/sitemap.xml`.
 - Add metadata fields such as title, path, locale, book, version, and subpage if you want filtering later.
 - Set `AI_SEARCH_INSTANCE_NAME` as a Cloudflare Pages environment variable or local `.dev.vars` entry.
 - 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.
@@ -366,7 +368,7 @@ When enabled, `docsector build` can generate:
 | `functions/assistant.js` | Cloudflare Pages Function for browser assistant requests |
 | `dist/spa/sitemap.xml` | Default crawler sitemap advertised from `robots.txt` |
 | `dist/spa/robots.txt` | Crawler policy with `Sitemap: /sitemap.xml` |
-| `dist/spa/ai-search-sitemap.xml` | Markdown-focused sitemap for AI Search crawling |
+| `dist/spa/ai-search-sitemap.xml` | Markdown-focused sitemap for explicit AI Search Website data source configuration |
 | `dist/spa/.well-known/ai-search/manifest.json` | Source metadata for indexed documentation pages |
 | `dist/spa/_routes.json` | Routes the internal assistant endpoint to the Pages Function |
 
@@ -617,7 +619,7 @@ Notes:
 - `aiTrain`, `search`, and `aiInput` accept `yes` / `no` (or booleans).
 - Default scope is only `User-agent: *`.
 - Build patch is idempotent: repeated builds do not duplicate `Content-Signal` lines.
-- Build also keeps `Sitemap: /sitemap.xml` discoverable in `robots.txt` so crawlers can find the generated sitemap automatically.
+- Build also keeps `Sitemap: /sitemap.xml` discoverable at the end of `robots.txt` so crawlers can find the generated sitemap automatically.
 
 ### Validate
 
@@ -732,6 +734,8 @@ npm install
 
 This creates a minimal project with `quasar.config.js`, `docsector.config.js`, `src/pages/`, `src/i18n/`, and `public/` — all powered by the docsector-reader engine.
 
+The scaffolded `quasar.config.js` delegates to `createQuasarConfig()`, which registers Docsector virtual registries and keeps the engine router out of Vite dependency optimization so modules like `virtual:docsector-books` resolve during dev and build.
+
 ### 💻 Development
 
 ```bash

package/bin/docsector.js

@@ -24,7 +24,7 @@ const packageRoot = resolve(__dirname, '..')
 const args = process.argv.slice(2)
 const command = args[0]
 
-const VERSION = '4.5.2'
+const VERSION = '4.5.4'
 const AUTHORING_SKILL_NAME = 'docsector-documentation-authoring'
 const AUTHORING_SKILL_DESCRIPTION = 'Author Docsector documentation with Markdown, custom blocks, MCP, and WebMCP.'
 const AUTHORING_SKILL_PUBLIC_PATH = `/.well-known/agent-skills/${AUTHORING_SKILL_NAME}/SKILL.md`
@@ -157,6 +157,32 @@ export default {
   // sitemap.xml is still generated with root-relative URLs when omitted.
   // siteUrl: 'https://docs.example.com',
 
+  // @ Home page source (optional)
+  // Use a remote README.md as homepage content at build-time.
+  // Falls back to local src/pages/Homepage.{lang}.md on fetch failure by default.
+  // homePage: {
+  //   source: 'remote-readme', // 'local' | 'remote-readme'
+  //   remoteReadmeUrl: 'https://raw.githubusercontent.com/your-org/your-repo/main/README.md',
+  //   timeoutMs: 8000,
+  //   fallbackToLocal: true
+  // },
+
+  // --- Language configs ---
+
+  // @ Languages
+  languages: [
+    {
+      image: '/images/flags/united-states-of-america.png',
+      label: 'English (US)',
+      value: 'en-US'
+    }
+  ],
+
+  // @ Default language
+  defaultLanguage: 'en-US'
+
+  // --- AI configs ---
+
   // @ MCP (Model Context Protocol)
   // Uncomment to enable an MCP server at /mcp for AI assistant integration.
   // Requires Cloudflare Pages Functions (or compatible serverless platform).
@@ -197,16 +223,6 @@ export default {
   //   }
   // },
 
-  // @ Home page source (optional)
-  // Use a remote README.md as homepage content at build-time.
-  // Falls back to local src/pages/Homepage.{lang}.md on fetch failure by default.
-  // homePage: {
-  //   source: 'remote-readme', // 'local' | 'remote-readme'
-  //   remoteReadmeUrl: 'https://raw.githubusercontent.com/your-org/your-repo/main/README.md',
-  //   timeoutMs: 8000,
-  //   fallbackToLocal: true
-  // },
-
   // @ Homepage Link headers for agent discovery (optional)
   // linkHeaders: {
   //   enabled: true,
@@ -270,19 +286,7 @@ export default {
   //       url: '${AUTHORING_SKILL_PUBLIC_PATH}'
   //     }
   //   ]
-  // },
-
-  // @ Languages
-  languages: [
-    {
-      image: '/images/flags/united-states-of-america.png',
-      label: 'English (US)',
-      value: 'en-US'
-    }
-  ],
-
-  // @ Default language
-  defaultLanguage: 'en-US'
+  // }
 }
 `
 
@@ -437,7 +441,10 @@ export default {
   label: 'Guide',
   icon: 'school',
   order: 1,
-  color: 'secondary'
+  color: {
+    active: 'white',
+    inactive: 'white'
+  }
 }
 `
 
@@ -635,7 +642,6 @@ const TEMPLATE_ROBOTS_TXT = `\
 User-agent: *
 Allow: /
 Content-Signal: ai-train=yes, search=yes, ai-input=yes
-Sitemap: /sitemap.xml
 
 # Explicitly allow AI crawlers
 # OpenAI
@@ -790,7 +796,7 @@ npm run build
 \`\`\`
 
 The optimized SPA output will be in \`dist/spa/\`.
-Docsector also generates \`dist/spa/sitemap.xml\` and keeps \`robots.txt\` discoverable with \`Sitemap: /sitemap.xml\`. Set \`siteUrl\` in \`docsector.config.js\` when you want absolute sitemap URLs.
+Docsector also generates \`dist/spa/sitemap.xml\` and appends \`Sitemap: /sitemap.xml\` to the end of \`dist/spa/robots.txt\` during build. Set \`siteUrl\` in \`docsector.config.js\` when you want absolute sitemap URLs.
 `
 
 // =============================================================================

package/docsector.config.js

@@ -82,16 +82,16 @@ export default {
       namespace: '',
       accountIdEnv: 'CLOUDFLARE_ACCOUNT_ID',
       apiTokenEnv: 'CLOUDFLARE_API_TOKEN',
-      model: '@cf/meta/llama-3.3-70b-instruct-fp8-fast',
+      model: '@cf/meta/llama-4-scout-17b-16e-instruct',
       retrievalType: 'vector',
-      maxResults: 6,
+      maxResults: 10,
       matchThreshold: 0.4,
       contextExpansion: 1,
       queryRewrite: {
         enabled: true
       },
       reranking: {
-        enabled: false,
+        enabled: true,
         model: '@cf/baai/bge-reranker-base',
         matchThreshold: 0.4
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "4.5.2",
+  "version": "4.5.4",
   "description": "A documentation rendering engine built with Vue 3, Quasar v2 and Vite. Transform Markdown into beautiful, navigable documentation sites.",
   "productName": "Docsector Reader",
   "author": "Rodrigo de Araujo Vieira",

package/public/.well-known/agent-skills/docsector-documentation-authoring/references/block-catalog.md

@@ -309,9 +309,11 @@ Use raw HTML only when Markdown is not expressive enough or when authoring Docse
 <div data-kind="secondary-note">
   This block uses raw HTML inside the page source.
 </div>
+
+Press <kbd>⌘</kbd> + <kbd>B</kbd> to toggle bold text.
 ```
 
-Prefer plain Markdown first. Keep raw markup readable because documentation content still needs maintenance.
+Prefer plain Markdown first. Use `<kbd>...</kbd>` for keyboard shortcuts that should read like GitBook-style keycaps. Keep raw markup readable because documentation content still needs maintenance.
 
 ## Renderer and Parser References
 

package/public/robots.txt

@@ -1,6 +1,5 @@
 User-agent: *
 Allow: /
-Sitemap: /sitemap.xml
 
 User-agent: Cloudflare-AI-Search
 Allow: /

package/src/ai-assistant/server.js

@@ -251,7 +251,7 @@ function buildSystemPrompt (body, currentPageMarkdown = '') {
   const lines = [
     'You are Docsector Assistant, a concise documentation assistant.',
     'Answer using the indexed documentation context. If the answer is not in the docs, say so clearly.',
-    'Prefer short, actionable answers and cite the relevant source chunks when available.'
+    'Prefer short, actionable answers.'
   ]
 
   if (locale) lines.push(`User locale: ${locale}.`)

package/src/css/app.sass

@@ -20,6 +20,10 @@ body.body--light
   --task-list-checkbox-checked-bg: #5e4c1f
   --task-list-checkbox-checked-border: #4f3f18
   --task-list-checkbox-check: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill='none' stroke='%23ffffff' stroke-linecap='round' stroke-linejoin='round' stroke-width='2.3' d='M3.25 8.5 6.4 11.4 12.75 4.9'/%3E%3C/svg%3E")
+  --kbd-color: #272b33
+  --kbd-background: #f7f8fa
+  --kbd-border: #d5dae0
+  --kbd-shadow: inset 0 -1px 0 #c4cad3, 0 1px 2px rgba(15, 23, 42, 0.08)
 
   --q-primary-background: #FFF !important
 
@@ -58,6 +62,10 @@ body.body--dark
   --task-list-checkbox-checked-bg: #d3b874
   --task-list-checkbox-checked-border: #ebd08a
   --task-list-checkbox-check: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill='none' stroke='%23151515' stroke-linecap='round' stroke-linejoin='round' stroke-width='2.3' d='M3.25 8.5 6.4 11.4 12.75 4.9'/%3E%3C/svg%3E")
+  --kbd-color: #f3f5f7
+  --kbd-background: #2a303a
+  --kbd-border: #4d5663
+  --kbd-shadow: inset 0 -1px 0 #3a414d, 0 1px 2px rgba(0, 0, 0, 0.45)
 
   --q-light-in-dark-1: #ababab
   --q-light-in-dark-2: #c9c9c9
@@ -199,6 +207,27 @@ body.body--dark
     display: inline
     line-height: 0.85em
 
+  kbd
+    display: inline-flex
+    align-items: center
+    justify-content: center
+    min-width: 1.8em
+    padding: 0.18rem 0.42rem
+    margin: 0 0.1rem
+    border: 1px solid var(--kbd-border)
+    border-radius: 0.45rem
+    background: var(--kbd-background)
+    box-shadow: var(--kbd-shadow)
+    color: var(--kbd-color)
+    font-family: "Segoe UI", "Helvetica Neue", Arial, sans-serif
+    font-size: 0.85em
+    font-weight: 600
+    line-height: 1.1
+    letter-spacing: 0.01em
+    vertical-align: middle
+    white-space: nowrap
+    text-transform: none
+
   .katex
     color: inherit
     max-width: 100%

package/src/index.js

@@ -179,7 +179,7 @@ export function createDocsector (config = {}) {
     },
 
     contentSignals: {
-      enabled: false,
+      enabled: true,
       aiTrain: 'yes',
       search: 'yes',
       aiInput: 'yes',
@@ -189,7 +189,7 @@ export function createDocsector (config = {}) {
     },
 
     agentSkills: {
-      enabled: false,
+      enabled: true,
       path: '/.well-known/agent-skills/index.json',
       schema: 'https://schemas.agentskills.io/discovery/0.2.0/schema.json',
       skills: [],

package/src/pages/manual/basic/ai-assistant.overview.en-US.md

@@ -47,7 +47,7 @@ For cleaner retrieval, point the specific sitemap setting to:
 https://docs.example.com/ai-search-sitemap.xml
 ```
 
-The AI Search sitemap points to Markdown URLs, which are cleaner for retrieval than rendered SPA HTML. The manifest at `/.well-known/ai-search/manifest.json` lists titles, routes, locales, books, versions, and subpages for the same source set.
+The AI Search sitemap points to Markdown URLs, which are cleaner for retrieval than rendered SPA HTML. Docsector keeps it available for explicit Cloudflare configuration, but does not auto-advertise it from `robots.txt` to avoid duplicate indexing alongside `/sitemap.xml`. The manifest at `/.well-known/ai-search/manifest.json` lists titles, routes, locales, books, versions, and subpages for the same source set.
 
 ## Runtime Endpoint
 

package/src/pages/manual/basic/ai-assistant.overview.pt-BR.md

@@ -47,7 +47,7 @@ Para uma recuperação mais limpa, aponte a configuração de sitemap específic
 https://docs.example.com/ai-search-sitemap.xml
 ```
 
-O sitemap do AI Search aponta para URLs Markdown, que são mais limpas para recuperação do que HTML renderizado pela SPA. O manifest em `/.well-known/ai-search/manifest.json` lista títulos, rotas, locales, books, versões e subpáginas do mesmo conjunto de fontes.
+O sitemap do AI Search aponta para URLs Markdown, que são mais limpas para recuperação do que HTML renderizado pela SPA. O Docsector mantém esse arquivo disponível para configuração explícita no Cloudflare, mas não o anuncia automaticamente em `robots.txt`, para evitar indexação duplicada junto com `/sitemap.xml`. O manifest em `/.well-known/ai-search/manifest.json` lista títulos, rotas, locales, books, versões e subpáginas do mesmo conjunto de fontes.
 
 ## Endpoint Runtime
 

package/src/pages/manual/content/blocks/raw-html.overview.en-US.md

@@ -2,7 +2,7 @@
 
 Raw HTML can be used inside Markdown when the native Markdown syntax is not expressive enough.
 
-This is useful for custom wrappers, inline labels, embedded elements, and Docsector-specific custom elements such as expandable blocks and quick links.
+This is useful for custom wrappers, inline labels, keyboard shortcut keycaps, embedded elements, and Docsector-specific custom elements such as expandable blocks and quick links.
 
 ## Markdown Example
 
@@ -10,10 +10,13 @@ This is useful for custom wrappers, inline labels, embedded elements, and Docsec
 <div data-kind="secondary-note">
   This block uses raw HTML inside the page source.
 </div>
+
+Press <kbd>⌘</kbd> + <kbd>B</kbd> to toggle bold text.
 ```
 
 ## Notes
 
 - Prefer plain Markdown first when it already solves the problem.
 - Use raw HTML when you need structure or attributes that Markdown does not provide.
+- Author GitBook-style keyboard shortcuts with `<kbd>...</kbd>` when you want keycaps inside normal prose.
 - Keep the markup readable, because documentation content still needs to be maintained by humans.

package/src/pages/manual/content/blocks/raw-html.showcase.en-US.md

@@ -9,4 +9,8 @@
 
 ### Inline Badge
 
-Use <span style="padding: 0.15rem 0.45rem; border: 1px solid currentColor; border-radius: 999px;">beta</span> labels directly inside a sentence.
+Use <span style="padding: 0.15rem 0.45rem; border: 1px solid currentColor; border-radius: 999px;">beta</span> labels directly inside a sentence.
+
+### Keyboard Shortcuts
+
+Use <kbd>⌘</kbd> + <kbd>B</kbd> for bold, <kbd>⌘</kbd> + <kbd>K</kbd> to open quick search, and <kbd>Shift</kbd> + <kbd>Alt</kbd> + <kbd>S</kbd> for multi-key shortcuts.

package/src/pages/manual.index.js

@@ -875,8 +875,8 @@ export default {
     },
     metadata: {
       tags: {
-        'en-US': 'raw html markup inline block custom elements markdown',
-        'pt-BR': 'html bruto marcação inline bloco elementos customizados markdown'
+        'en-US': 'raw html markup inline block custom elements markdown keyboard shortcut shortcuts kbd keycap gitbook',
+        'pt-BR': 'html bruto marcação inline bloco elementos customizados markdown teclado atalho atalhos kbd keycap gitbook'
       }
     }
   },

package/src/quasar.factory.js

@@ -74,6 +74,28 @@ function normalizePathForMatch (path) {
 
 const CURRENT_VERSION_KEY = '__current__'
 
+const DOCSECTOR_VIRTUAL_MODULE_IDS = Object.freeze([
+  'virtual:docsector-books',
+  'virtual:docsector-homepage-override',
+  'virtual:docsector-code-examples',
+  'virtual:docsector-git-dates'
+])
+
+const DOCSECTOR_CONSUMER_OPTIMIZE_DEPS_EXCLUDE = Object.freeze([
+  '@docsector/docsector-reader',
+  '@docsector/docsector-reader/src/App.vue',
+  '@docsector/docsector-reader/src/router/index',
+  '@docsector/docsector-reader/src/router/index.js',
+  '@docsector/docsector-reader/src/router/routes',
+  '@docsector/docsector-reader/src/router/routes.js',
+  'node_modules/@docsector/docsector-reader/src/App.vue',
+  'node_modules/@docsector/docsector-reader/src/router/index',
+  'node_modules/@docsector/docsector-reader/src/router/index.js',
+  'node_modules/@docsector/docsector-reader/src/router/routes',
+  'node_modules/@docsector/docsector-reader/src/router/routes.js',
+  ...DOCSECTOR_VIRTUAL_MODULE_IDS
+])
+
 function trimSlashes (value) {
   return String(value || '').replace(/^\/+|\/+$/g, '')
 }
@@ -1936,6 +1958,16 @@ function collectStandardSitemapEntries ({ pagesDir, pageEntries = [], defaultLan
   return entries
 }
 
+export function getAdvertisedRobotsSitemapPaths ({ sitemapEnabled = true } = {}) {
+  const paths = []
+
+  if (sitemapEnabled) {
+    paths.push('/sitemap.xml')
+  }
+
+  return paths
+}
+
 /**
  * Create a Vite plugin that generates static `.md` files at build time.
  *
@@ -2439,9 +2471,7 @@ export async function onRequest (context) {
         }
       }
 
-      const robotsSitemapPaths = []
-      if (sitemapEnabled) robotsSitemapPaths.push('/sitemap.xml')
-      if (aiSearchSitemapGenerated) robotsSitemapPaths.push('/ai-search-sitemap.xml')
+      const robotsSitemapPaths = getAdvertisedRobotsSitemapPaths({ sitemapEnabled })
 
       if (robotsSitemapPaths.length > 0) {
         const robotsPath = resolve(distDir, 'robots.txt')
@@ -3203,21 +3233,23 @@ export function createQuasarConfig (options = {}) {
           ...(viteConf.optimizeDeps.include || []),
           'vue', 'vue-router', 'vuex', 'vue-i18n',
           'prismjs', 'markdown-it', 'markdown-it-attrs',
+          'markdown-it-task-lists', 'markdown-it-texmath',
           'hjson', 'q-colorize-mixin', 'mermaid'
         ]
 
-        // Exclude boot files and the router from pre-bundling.
+        // Exclude boot files and Docsector runtime entry points from pre-bundling.
         // Boot files (especially boot/i18n) import the consumer's src/i18n/index.js
         // which uses import.meta.glob — a compile-time Vite directive that only
         // works in source files. If pre-bundled, the glob calls become dead code
         // and no i18n messages are loaded.
-        // The router is excluded because routes.js imports consumer content via
-        // the `pages` alias. If pre-bundled, consumer content gets embedded in
-        // the optimizer cache whose hash doesn't track source file changes,
-        // causing stale routes after editing page registry files.
+        // In consumer mode, the package router also imports Vite virtual modules
+        // and consumer content via the `pages` alias. If pre-bundled, Vite can
+        // try resolving those virtual IDs before Docsector's plugins handle them,
+        // or embed stale consumer registry content in the optimizer cache.
         viteConf.optimizeDeps.exclude = [
           ...(viteConf.optimizeDeps.exclude || []),
-          'boot/i18n', 'boot/store', 'boot/QZoom', 'boot/axios'
+          'boot/i18n', 'boot/store', 'boot/QZoom', 'boot/axios',
+          ...(!isStandalone ? DOCSECTOR_CONSUMER_OPTIMIZE_DEPS_EXCLUDE : [])
         ]
 
         if (!isStandalone) {

package/src/sitemap.js

@@ -76,28 +76,37 @@ export function appendSitemapsToRobots (robotsContent, { sitemaps = [], siteUrl
     ? robotsContent
     : 'User-agent: *\nAllow: /\n'
 
-  const existingIdentities = new Set(
-    input
-      .replace(/\r\n/g, '\n')
-      .split('\n')
-      .map(line => line.match(/^\s*Sitemap\s*:\s*(.+?)\s*$/i)?.[1])
-      .filter(Boolean)
-      .map(normalizeSitemapIdentity)
-  )
-
-  const addedIdentities = new Set()
-  const sitemapLines = (Array.isArray(sitemaps) ? sitemaps : [sitemaps])
+  const bodyLines = []
+  const existingSitemaps = []
+
+  for (const line of input.replace(/\r\n/g, '\n').split('\n')) {
+    const sitemap = line.match(/^\s*Sitemap\s*:\s*(.+?)\s*$/i)?.[1]
+    if (sitemap) {
+      existingSitemaps.push(sitemap)
+      continue
+    }
+
+    bodyLines.push(line)
+  }
+
+  const seenIdentities = new Set()
+  const normalizedSitemaps = [
+    ...(Array.isArray(sitemaps) ? sitemaps : [sitemaps]),
+    ...existingSitemaps
+  ]
     .filter(Boolean)
     .map(sitemap => resolveSitemapUrl(sitemap, siteUrl))
     .filter(sitemap => {
       const identity = normalizeSitemapIdentity(sitemap)
-      if (existingIdentities.has(identity) || addedIdentities.has(identity)) return false
-      addedIdentities.add(identity)
+      if (seenIdentities.has(identity)) return false
+      seenIdentities.add(identity)
       return true
     })
-    .map(sitemap => `Sitemap: ${sitemap}`)
 
-  if (sitemapLines.length === 0) return input
+  if (normalizedSitemaps.length === 0) return input
+
+  const body = bodyLines.join('\n').replace(/\s+$/g, '')
+  const sitemapLines = normalizedSitemaps.map(sitemap => `Sitemap: ${sitemap}`)
 
-  return `${input.replace(/\s+$/g, '')}\n${sitemapLines.join('\n')}\n`
+  return `${body}\n\n${sitemapLines.join('\n')}\n`
 }