@docsector/docsector-reader 4.5.0 → 4.5.3

package/README.md

@@ -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
@@ -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.0'
+const VERSION = '4.5.3'
 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`
@@ -437,7 +437,10 @@ export default {
   label: 'Guide',
   icon: 'school',
   order: 1,
-  color: 'secondary'
+  color: {
+    active: 'white',
+    inactive: 'white'
+  }
 }
 `
 

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.0",
+  "version": "4.5.3",
   "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/src/components/DFooter.vue

@@ -2,7 +2,19 @@
   <footer class="d-footer" role="contentinfo">
     <div class="d-footer__content">
       <span class="d-footer__label">Powered by</span>
-      <span class="d-footer__brand">Docsector</span>
+      <q-btn
+        class="d-footer__brand"
+        unelevated
+        dense
+        no-caps
+        color="white"
+        text-color="dark"
+        label="Docsector"
+        href="https://docsector.com"
+        target="_blank"
+        rel="noopener noreferrer"
+        aria-label="Open Docsector website"
+      />
     </div>
   </footer>
 </template>
@@ -15,7 +27,7 @@ defineOptions({ name: 'DFooter' })
 .d-footer
   width: 100%
   background: var(--q-primary, #655529)
-  color: #ffffff
+  color: #ffffff !important
 
   .d-footer__content
     max-width: 1200px
@@ -33,7 +45,10 @@ defineOptions({ name: 'DFooter' })
     opacity: 0.84
 
   .d-footer__brand
-    font-weight: 700
+    box-shadow: inset 0 0 0 1px rgba(0, 0, 0, 0.1)
+
+    .q-btn__content
+      font-weight: 700
 
 @media (max-width: 599px)
   .d-footer

package/src/components/DPage.vue

@@ -639,6 +639,8 @@ watch(() => route.fullPath, () => {
     overflow: auto
     box-shadow: -16px 0 40px rgba(15, 23, 42, 0.22)
 
+.d-mobile-anchor-dialog__panel
+  opacity: 0.8
 body.body--dark
   .d-mobile-anchor-dialog__panel
     background: rgba(15, 23, 42, 0.9)

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/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, '')
 }
@@ -3203,21 +3225,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) {