@docsector/docsector-reader 1.7.0 → 2.0.0

package/.eslintrc.cjs

@@ -1,6 +1,8 @@
 module.exports = {
   root: true,
 
+  ignorePatterns: ['docsector.config.js'],
+
   parserOptions: {
     ecmaVersion: 2022,
     sourceType: 'module'

package/README.md

@@ -41,6 +41,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 ## ✨ Features
 
 - 📝 **Markdown Rendering** — Write docs in Markdown, rendered with syntax highlighting (Prism.js)
+- 🧱 **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
 - 🚨 **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
@@ -49,6 +50,9 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🔎 **Search** — Menu search across all documentation content and tags
 - 🌐 **WebMCP Browser Tools** — Registers in-page tools for browser agents with `registerTool` and optional `provideContext` fallback
 - 📱 **Responsive** — Mobile-friendly with collapsible sidebar and drawers
+- 📚 **Book Tabs with Per-State Colors** — Define `*.book.js` tabs with icons, order, and `color.active` / `color.inactive`
+- 🔀 **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
 - 🏷️ **Status Badges** — Mark pages as `done`, `draft`, or `empty` 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
@@ -59,6 +63,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🧭 **Content Signals** — Injects `Content-Signal` policy in `robots.txt` with deterministic, idempotent build output
 - 🏠 **Markdown Home at Root** — Homepage is rendered from `src/pages/Homepage.{lang}.md` directly at `/`
 - 🌍 **Remote README as Home** — Optional build-time remote README source for homepage with automatic local fallback
+- 🧬 **Scaffolded Homepage Override Wiring** — New consumer projects automatically wire `virtual:docsector-homepage-override` into i18n message building
 - 🧭 **Quick Links Custom Element** — Use `<d-quick-links>` and `<d-quick-link>` in Markdown to render rich home navigation cards
 - 🗂️ **API Catalog Well-Known** — Auto-generates `/.well-known/api-catalog` as Linkset JSON for machine-readable API discovery
 - ⚙️ **Single Config File** — Customize branding, links, and languages via `docsector.config.js`
@@ -92,7 +97,7 @@ When `mcp` is configured, `docsector build` generates:
 
 | File | Purpose |
 |---|---|
-| `dist/spa/mcp-pages.json` | Page index (title, path, type) for search |
+| `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 |
@@ -767,16 +772,19 @@ Consumer projects use the `buildMessages` helper from the engine:
 
 ```javascript
 import { buildMessages } from '@docsector/docsector-reader/i18n'
+import homePageOverride from 'virtual:docsector-homepage-override'
 
 const langModules = import.meta.glob('./languages/*.hjson', { eager: true })
 const mdModules = import.meta.glob('../pages/**/*.md', { eager: true, query: '?raw', import: 'default' })
 
 import boot from 'pages/boot'
-import pages from 'pages'
+import { books } from 'virtual:docsector-books'
 
-export default buildMessages({ langModules, mdModules, pages, boot })
+export default buildMessages({ langModules, mdModules, books, boot, homePageOverride })
 ```
 
+> `books` is the preferred source because it preserves per-book registries and avoids path collisions when two books reuse the same route key.
+
 ### Language files
 
 Place HJSON locale files in `src/i18n/languages/`:
@@ -812,7 +820,10 @@ my-docs/
 ├── package.json
 ├── src/
 │   ├── pages/
-│   │   ├── index.js           # Page registry (routes + metadata)
+│   │   ├── manual.book.js     # Manual tab metadata (icon, order, active/inactive colors)
+│   │   ├── manual.index.js    # Manual page registry (routes + metadata)
+│   │   ├── guide.book.js      # Guide tab metadata (icon, order, active/inactive colors)
+│   │   ├── guide.index.js     # Guide page registry (routes + metadata)
 │   │   ├── boot.js            # Boot page data
 │   │   ├── guide/             # Guide pages (.md files)
 │   │   └── manual/            # Manual pages (.md files)
@@ -832,17 +843,54 @@ my-docs/
 
 ---
 
+## ⚠️ Migrating from 1.x to 2.0
+
+- Split the legacy `src/pages/index.js` registry into per-book files such as `src/pages/manual.book.js`, `src/pages/manual.index.js`, `src/pages/guide.book.js`, and `src/pages/guide.index.js`.
+- Update i18n wiring to import `books` from `virtual:docsector-books` and pass it to `buildMessages({ ... })`.
+- Rename `config.type` to `config.book` in page definitions. Legacy fallback still works, but `config.book` is the supported API moving forward.
+
+---
+
+## 📚 Defining Books (Tabs)
+
+Each documentation tab is defined by a `*.book.js` file paired with a matching `*.index.js` registry.
+
+```javascript
+import { defineBook } from '@docsector/docsector-reader'
+
+export default defineBook({
+  id: 'guide',
+  label: 'Guide',
+  icon: 'school',
+  order: 2,
+  color: {
+    active: 'white',
+    inactive: 'secondary'
+  }
+})
+```
+
+Notes:
+
+- `color.active` and `color.inactive` control the tab text color for each state.
+- Color values accept Quasar tokens (`secondary`, `red-6`), CSS variables (`--brand-color` or `var(--brand-color)`), and plain CSS colors (`white`, `#fff`, `rgb(...)`).
+- Legacy `color: 'secondary'` still works, but the object form is the recommended API.
+- Tabs are ordered by `order`.
+
+---
+
 ## 📄 Adding Pages
 
-1️⃣ Register in `src/pages/index.js`:
+1️⃣ Register in `src/pages/manual.index.js` (or `src/pages/guide.index.js`):
 
 ```javascript
+import { definePage } from '@docsector/docsector-reader'
+
 export default {
-  '/manual/my-section/my-page': {
+  '/my-section/my-page': definePage({
     config: {
       icon: 'description',
       status: 'done',        // 'done' | 'draft' | 'empty'
-      type: 'manual',        // 'guide' | 'manual'
       menu: {
         header: { label: '.my-section', icon: 'category' }
       },
@@ -852,10 +900,16 @@ export default {
       'en-US': { title: 'My Page' },
       'pt-BR': { title: 'Minha Página' }
     }
-  }
+  })
 }
 ```
 
+Notes:
+
+- In `manual.index.js`, route keys are relative to the `manual` book (for example `'/my-section/my-page'` becomes `/manual/my-section/my-page/...`).
+- You only need to set `config.book` when overriding the inferred book from the registry file.
+- When `showcase` or `vs` are enabled, the subpage toolbar aligns with the content width on desktop and becomes a bottom action bar on mobile.
+
 2️⃣ Create Markdown files:
 
 ```
@@ -863,6 +917,34 @@ src/pages/manual/my-section/my-page.overview.en-US.md
 src/pages/manual/my-section/my-page.overview.pt-BR.md
 ```
 
+### Internal Links / Menu Shortcuts
+
+Use `config.link.to` when an entry should appear in menus but redirect immediately to another internal page.
+
+```javascript
+import { definePage } from '@docsector/docsector-reader'
+
+export default {
+  '/getting-started': definePage({
+    config: {
+      link: {
+        to: '/guide/getting-started/overview/'
+      }
+    },
+    data: {
+      'en-US': { title: 'Getting started' },
+      'pt-BR': { title: 'Começando' }
+    }
+  })
+}
+```
+
+Notes:
+
+- For shortcut pages, `link.to` and `data` are enough.
+- `icon` and `status` automatically fall back to the destination page when omitted.
+- Internal links redirect directly to the target route instead of rendering `overview` / `showcase` / `vs` locally.
+
 ### GitHub-Style Alert Example
 
 ```markdown
@@ -896,9 +978,12 @@ docsector help                 # Show help
 
 | Import path | Export | Description |
 |---|---|---|
+| `@docsector/docsector-reader` | `createDocsector()` | Main helper for `docsector.config.js` objects |
+| `@docsector/docsector-reader` | `defineBook()` | Define `*.book.js` tab metadata with active/inactive colors |
+| `@docsector/docsector-reader` | `definePage()` | Define page registry entries, including internal shortcut pages |
 | `@docsector/docsector-reader/quasar-factory` | `createQuasarConfig()` | Config factory for consumer projects |
 | `@docsector/docsector-reader/quasar-factory` | `configure()` | No-op wrapper (avoids needing `quasar` dep) |
-| `@docsector/docsector-reader/i18n` | `buildMessages()` | Build i18n messages from globs + pages |
+| `@docsector/docsector-reader/i18n` | `buildMessages()` | Build i18n messages from globs + book/page registries |
 | `@docsector/docsector-reader/i18n` | `filter()` | Filter i18n messages by locale |
 
 ---

package/bin/docsector.js

@@ -23,7 +23,7 @@ const packageRoot = resolve(__dirname, '..')
 const args = process.argv.slice(2)
 const command = args[0]
 
-const VERSION = '1.7.0'
+const VERSION = '2.0.0'
 
 const HELP = `
   Docsector Reader v${VERSION}
@@ -71,7 +71,7 @@ function getTemplatePackageJson (name) {
       serve: 'docsector serve'
     },
     dependencies: {
-      '@docsector/docsector-reader': '^0.6.0',
+      '@docsector/docsector-reader': `^${VERSION}`,
       '@quasar/extras': '^1.16.12',
       'quasar': '^2.16.6',
       'vue': '^3.5.13',
@@ -264,6 +264,7 @@ const TEMPLATE_CSS_STUB = `\
 const TEMPLATE_I18N_INDEX = `\
 // @ Import i18n message builder from Docsector Reader
 import { buildMessages } from '@docsector/docsector-reader/i18n'
+import homePageOverride from 'virtual:docsector-homepage-override'
 
 // @ Import language HJSON files (Vite-compatible eager import)
 const langModules = import.meta.glob('./languages/*.hjson', { eager: true })
@@ -272,9 +273,9 @@ const mdModules = import.meta.glob('../pages/**/*.md', { eager: true, query: '?r
 
 // @ Import pages
 import boot from 'pages/boot'
-import pages from 'pages'
+import { allPages as pages } from 'virtual:docsector-books'
 
-export default buildMessages({ langModules, mdModules, pages, boot })
+export default buildMessages({ langModules, mdModules, pages, boot, homePageOverride })
 `
 
 const TEMPLATE_I18N_HJSON = `\
@@ -382,14 +383,24 @@ const TEMPLATE_I18N_HJSON = `\
 }
 `
 
+const TEMPLATE_PAGES_GUIDE_BOOK = `\
+export default {
+  id: 'guide',
+  label: 'Guide',
+  icon: 'school',
+  order: 1,
+  color: 'secondary'
+}
+`
+
 const TEMPLATE_PAGES_INDEX = `\
 /**
- * Pages Registry
+ * Guide Pages Registry
  *
- * Define your documentation pages here. Each key is a URL path,
- * and each value configures the page's type, icon, status, and titles.
+ * Define guide pages here. Each key is a URL path,
+ * and each value configures the page's book, icon, status, and titles.
  *
- * config.type: top-level route prefix — 'manual', 'guide', etc.
+ * config.book: top-level route prefix — 'guide', 'manual', etc.
  * config.status: 'done' | 'draft' | 'empty'
  * config.meta.description: string or localized object for SEO/social description
  * config.icon: Material Design icon name
@@ -409,7 +420,7 @@ export default {
           'en-US': 'Get started quickly with setup and project structure.'
         }
       },
-      type: 'guide',
+      book: 'guide',
       menu: {
         header: {
           icon: 'school',
@@ -951,7 +962,8 @@ Here's an overview of the project files:
 | \`docsector.config.js\` | Branding, links, languages, and GitHub config |
 | \`quasar.config.js\` | Quasar/Vite build configuration (via factory) |
 | \`.markdownlint.json\` | Markdown lint rules (allows Docsector custom tags) |
-| \`src/pages/index.js\` | Page registry — defines all documentation pages |
+| \`src/pages/guide.book.js\` | Guide book definition (tab metadata) |
+| \`src/pages/guide.index.js\` | Guide page registry (routes + metadata) |
 | \`src/pages/boot.js\` | Boot metadata for the home page |
 | \`src/pages/Homepage.en-US.md\` | Home page content in Markdown |
 | \`src/pages/404Page.vue\` | Not found page |
@@ -962,8 +974,9 @@ Here's an overview of the project files:
 
 ## Adding a Page
 
-1. Register the page in \`src/pages/index.js\`
-2. Create the Markdown file at \`src/pages/{type}/{path}.overview.{lang}.md\`
+1. Register the page in \`src/pages/guide.index.js\`
+2. Set \`config.book\` (for example: \`'guide'\`)
+3. Create the Markdown file at \`src/pages/{book}/{path}.overview.{lang}.md\`
 3. The page will automatically appear in the sidebar navigation
 
 ## Customization
@@ -1081,7 +1094,8 @@ function initProject (name) {
     ['src/css/app.sass', TEMPLATE_CSS_STUB],
     ['src/i18n/index.js', TEMPLATE_I18N_INDEX],
     ['src/i18n/languages/en-US.hjson', TEMPLATE_I18N_HJSON],
-    ['src/pages/index.js', TEMPLATE_PAGES_INDEX],
+    ['src/pages/guide.book.js', TEMPLATE_PAGES_GUIDE_BOOK],
+    ['src/pages/guide.index.js', TEMPLATE_PAGES_INDEX],
     ['src/pages/boot.js', TEMPLATE_PAGES_BOOT],
     ['src/pages/Homepage.en-US.md', TEMPLATE_HOMEPAGE_MD],
     ['src/pages/404Page.vue', TEMPLATE_404_PAGE],
@@ -1119,7 +1133,8 @@ function initProject (name) {
   console.log('        │   └── languages/')
   console.log('        │       └── en-US.hjson')
   console.log('        └── pages/')
-  console.log('            ├── index.js')
+  console.log('            ├── guide.book.js')
+  console.log('            ├── guide.index.js')
   console.log('            ├── boot.js')
   console.log('            ├── Homepage.en-US.md')
   console.log('            ├── 404Page.vue')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "1.7.0",
+  "version": "2.0.0",
   "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/src/components/DH1.vue

@@ -4,6 +4,7 @@ import { useStore } from 'vuex'
 import { useI18n } from "vue-i18n";
 
 import useNavigator from '../composables/useNavigator'
+import { pageTitleI18nPath } from '../i18n/path'
 
 const props = defineProps({
   id: {
@@ -22,7 +23,7 @@ const heading = computed(() => {
 
   let h = ''
   if (base && absolute) {
-    h = t(`_.${base}._`)
+    h = t(pageTitleI18nPath(base))
   }
 
   return h

package/src/components/DMenu.vue

@@ -1,5 +1,5 @@
 <script setup>
-import { ref, computed, onMounted, onBeforeUnmount } from 'vue'
+import { ref, computed, onMounted, onBeforeUnmount, watch } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 import { useQuasar, scroll, openURL } from 'quasar'
 import { useI18n } from 'vue-i18n'
@@ -7,6 +7,8 @@ import { useI18n } from 'vue-i18n'
 import tags from '@docsector/tags'
 import DMenuItem from './DMenuItem.vue'
 import docsectorConfig from 'docsector.config.js'
+import { allBooks } from 'virtual:docsector-books'
+import { namespacedLabelI18nPath, routeSubpageSourceI18nPath } from '../i18n/path'
 
 const $q = useQuasar()
 const $route = useRoute()
@@ -29,6 +31,27 @@ const subpage = computed(() => {
   return child.substring(parent.length)
 })
 
+const defaultBookId = computed(() => {
+  const sortedBooks = [...(allBooks || [])]
+    .filter(book => book && typeof book.id === 'string' && book.id.length > 0)
+    .sort((a, b) => {
+      const orderA = Number.isFinite(a.order) ? a.order : Number.MAX_SAFE_INTEGER
+      const orderB = Number.isFinite(b.order) ? b.order : Number.MAX_SAFE_INTEGER
+      return orderA - orderB
+    })
+
+  return sortedBooks[0]?.id || null
+})
+
+const currentBookId = computed(() => {
+  const routeBook = $route.matched?.[0]?.meta?.book ?? $route.meta?.book ?? null
+  if (routeBook && routeBook !== 'home') {
+    return routeBook
+  }
+
+  return defaultBookId.value
+})
+
 const searchTerm = (term) => {
   if (term.length > 1) {
     term = term.toLowerCase()
@@ -76,7 +99,7 @@ const searchTermInI18nTexts = (route, term, locale) => {
   let source = null
   let found = false
   for (const subpage of subpages) {
-    const path = `_${route.replace(/_$/, '').replace(/\//g, '.')}.${subpage}.source`
+    const path = routeSubpageSourceI18nPath(route, subpage)
     const msgExists = te(path, locale)
     if (msgExists) {
       source = tm(path, locale)
@@ -99,7 +122,8 @@ const clearSearchTerm = () => {
 const getMenuItemHeaderLabel = (meta) => {
   const label = meta.menu.header.label
   if (label[0] === '.') { // Node path
-    const path = `_.${meta.type}${label}._`
+    const book = meta.book ?? meta.type ?? 'manual'
+    const path = namespacedLabelI18nPath(book, label)
     return t(path)
   }
   return label // String raw
@@ -156,38 +180,54 @@ onBeforeUnmount(() => {
   }
 })
 
-// # Events
-// Create
-const routes = $router.options.routes.slice(0, -2) // Delete last 2 routes
-const itemsArray = []
-
-let nodeBasepath = ''
-let nodeIndex = 0
-for (const [index, route] of routes.entries()) {
-  const item = Object.freeze({
-    path: route.path,
-    meta: route.meta
+const buildMenuItems = () => {
+  const routes = ($router.options.routes || []).slice(0, -2) // Delete last 2 routes
+  const activeBook = currentBookId.value
+
+  const filteredRoutes = routes.filter(route => {
+    const routeBook = route?.meta?.book ?? route?.meta?.type
+    if (!activeBook) return true
+    return routeBook === activeBook
   })
-  // # Route
-  const basepath = route.path.split('/')[2]
-  const header = route.meta.menu.header
-
-  if (header !== undefined && basepath !== nodeBasepath) {
-    nodeBasepath = basepath
-    nodeIndex = index
-    itemsArray[index] = []
-  } else if (header === undefined && basepath !== nodeBasepath) {
-    nodeBasepath = ''
-  }
 
-  if (nodeBasepath !== '') {
-    itemsArray[nodeIndex].push(item)
-  } else {
-    itemsArray.push(item)
+  const itemsArray = []
+
+  let nodeBasepath = ''
+  let nodeIndex = 0
+  for (const [index, route] of filteredRoutes.entries()) {
+    const item = Object.freeze({
+      path: route.path,
+      meta: route.meta
+    })
+
+    // # Route
+    const basepath = route.path.split('/')[2]
+    const header = route.meta?.menu?.header
+
+    if (header !== undefined && basepath !== nodeBasepath) {
+      nodeBasepath = basepath
+      nodeIndex = index
+      itemsArray[index] = []
+    } else if (header === undefined && basepath !== nodeBasepath) {
+      nodeBasepath = ''
+    }
+
+    if (nodeBasepath !== '') {
+      itemsArray[nodeIndex].push(item)
+    } else {
+      itemsArray.push(item)
+    }
   }
+
+  return Object.freeze(itemsArray.filter(item => item !== undefined))
+}
+
+const rebuildItems = () => {
+  items.value = buildMenuItems()
 }
 
-items.value = Object.freeze(itemsArray.filter(item => item !== undefined))
+rebuildItems()
+watch(currentBookId, rebuildItems)
 </script>
 
 <template>

package/src/components/DMenuItem.vue

@@ -4,6 +4,8 @@ import { useRoute } from 'vue-router'
 import { useQuasar } from 'quasar'
 import { useI18n } from 'vue-i18n'
 
+import { namespacedLabelI18nPath, routeTitleI18nPath } from '../i18n/path'
+
 const props = defineProps({
   items: {
     type: Number,
@@ -36,13 +38,17 @@ const getMenuItemHeaderBackground = () => {
 }
 
 const getMenuItemLabel = (item, index) => {
-  const path = `_${item.path.replace(/_$/, '').replace(/\//g, '.')}._`
-  return t(path)
+  return t(routeTitleI18nPath(item.path))
 }
 
 const getMenuItemSubheader = (meta) => {
-  const subheader = meta.menu.subheader
-  const path = `_.${meta.type}${subheader}._`
+  const subheader = meta.menu?.subheader
+  if (!subheader) {
+    return ''
+  }
+
+  const book = meta.book ?? meta.type ?? 'manual'
+  const path = namespacedLabelI18nPath(book, subheader)
 
   return t(path)
 }
@@ -95,7 +101,7 @@ const isMenuItemActive = (path) => {
 
 <template>
 <!-- Menu Separator - Subheader -->
-<q-item-section v-if="subitem.meta.menu.subheader">
+<q-item-section v-if="subitem.meta.menu?.subheader">
   <q-item-label class="label subheader" header>
     {{ getMenuItemSubheader(subitem.meta) }}
   </q-item-label>
@@ -123,7 +129,7 @@ const isMenuItemActive = (path) => {
 </q-item>
 
 <!-- Menu Separator -->
-<li v-if="subitem.meta.menu.separator" role="listitem">
+<li v-if="subitem.meta.menu?.separator" role="listitem">
   <q-separator
     :class="'separator' + (subitem.meta.menu.separator === true ? '' : subitem.meta.menu.separator)"
     role="separator"