@docsector/docsector-reader 2.0.6 → 2.1.0

package/src/i18n/helpers.js

@@ -116,12 +116,13 @@ export function filter (source) {
  * @param {Object} options.mdModules - Result of recursively globbing markdown files under ../pages with eager raw imports
  * @param {Object} [options.pages] - Legacy merged page registry from virtual:docsector-books (allPages)
  * @param {Object} [options.books] - Book registry from virtual:docsector-books (preferred, avoids path collisions)
+ * @param {Array} [options.pageEntries] - Version-aware page entries from virtual:docsector-books
  * @param {Object} options.boot - Boot meta from pages/boot.js
  * @param {string[]} [options.langs] - Language codes to process (auto-detected from langModules if omitted)
  * @param {Object<string,string>} [options.homePageOverride] - Optional per-language Home markdown override
  * @returns {Object} Complete i18n messages object keyed by locale
  */
-export function buildMessages ({ langModules, mdModules, pages, books, boot, langs, homePageOverride = {} }) {
+export function buildMessages ({ langModules, mdModules, pages, books, pageEntries, boot, langs, homePageOverride = {} }) {
   // Auto-detect languages from HJSON files if not provided
   if (!langs) {
     langs = Object.keys(langModules).map(key => {
@@ -133,8 +134,9 @@ export function buildMessages ({ langModules, mdModules, pages, books, boot, lan
 
   const i18n = {}
 
-  function load (topPage, path, subpage, lang) {
-    const key = `../pages/${topPage}/${path}.${subpage}.${lang}.md`
+  function load (topPage, path, subpage, lang, sourceRoot = '') {
+    const normalizedSourceRoot = String(sourceRoot || '').replace(/^\/+|\/+$/g, '')
+    const key = `../pages/${normalizedSourceRoot ? normalizedSourceRoot + '/' : ''}${topPage}/${path}.${subpage}.${lang}.md`
     const content = mdModules[key]
 
     if (!content) {
@@ -200,20 +202,30 @@ export function buildMessages ({ langModules, mdModules, pages, books, boot, lan
     return match[1].trim()
   }
 
-  const pageEntries = []
+  const resolvedPageEntries = []
 
-  if (books && typeof books === 'object' && Object.keys(books).length > 0) {
+  if (Array.isArray(pageEntries) && pageEntries.length > 0) {
+    for (const entry of pageEntries) {
+      resolvedPageEntries.push({
+        key: entry.pagePath,
+        page: entry.page,
+        fallbackBook: entry.book,
+        sourceRoot: entry.sourceRoot || '',
+        i18nSegments: entry.i18nSegments
+      })
+    }
+  } else if (books && typeof books === 'object' && Object.keys(books).length > 0) {
     for (const [bookId, book] of Object.entries(books)) {
       const routes = book?.routes || {}
       const fallbackBook = book?.config?.id || bookId || 'manual'
 
       for (const [key, page] of Object.entries(routes)) {
-        pageEntries.push({ key, page, fallbackBook })
+        resolvedPageEntries.push({ key, page, fallbackBook })
       }
     }
   } else {
     for (const [key, page] of Object.entries(pages || {})) {
-      pageEntries.push({ key, page, fallbackBook: null })
+      resolvedPageEntries.push({ key, page, fallbackBook: null })
     }
   }
 
@@ -249,8 +261,8 @@ export function buildMessages ({ langModules, mdModules, pages, books, boot, lan
     i18n[lang]._.home.overview.source = loadHomepage(lang)
 
     // @ Iterate pages
-    for (const entry of pageEntries) {
-      const { key, page, fallbackBook } = entry
+    for (const entry of resolvedPageEntries) {
+      const { key, page, fallbackBook, sourceRoot = '', i18nSegments: entryI18nSegments } = entry
       const path = key.startsWith('/') ? key.slice(1) : key
 
       const config = page.config
@@ -258,13 +270,13 @@ export function buildMessages ({ langModules, mdModules, pages, books, boot, lan
       const meta = page.meta || boot.meta
 
       const topPage = config?.book ?? config?.type ?? fallbackBook ?? 'manual'
-      if (i18n[lang]._[topPage] === undefined) {
-        i18n[lang]._[topPage] = {}
-      }
+      const i18nSegments = Array.isArray(entryI18nSegments) && entryI18nSegments.length > 0
+        ? entryI18nSegments
+        : [topPage, ...path.split('/').filter(Boolean)]
 
       // ---
 
-      const _ = path.split('/').reduce((accumulator, current) => {
+      const _ = i18nSegments.reduce((accumulator, current, index) => {
         let node = accumulator[current]
 
         // Set object if not exists
@@ -275,7 +287,7 @@ export function buildMessages ({ langModules, mdModules, pages, books, boot, lan
 
         // @ Set metadata
         // title
-        if (node._ === undefined) {
+        if (index === i18nSegments.length - 1 && node._ === undefined) {
           node._ = data?.[lang]?.title || data?.['*']?.title || data?.['en-US']?.title || ''
         }
 
@@ -283,6 +295,10 @@ export function buildMessages ({ langModules, mdModules, pages, books, boot, lan
           return node
         }
 
+        if (index < i18nSegments.length - 1) {
+          return node
+        }
+
         // Set subpages sources if not exists
         if (node.overview === undefined) {
           node.overview = {
@@ -307,7 +323,7 @@ export function buildMessages ({ langModules, mdModules, pages, books, boot, lan
         }
 
         return node
-      }, i18n[lang]._[topPage])
+      }, i18n[lang]._)
 
       // ---
 
@@ -322,14 +338,14 @@ export function buildMessages ({ langModules, mdModules, pages, books, boot, lan
 
       // @ Subpages
       // Overview
-      _.overview.source = load(topPage, path, 'overview', lang)
+      _.overview.source = load(topPage, path, 'overview', lang, sourceRoot)
       // showcase
       if (config.subpages?.showcase === true) {
-        _.showcase.source = load(topPage, path, 'showcase', lang)
+        _.showcase.source = load(topPage, path, 'showcase', lang, sourceRoot)
       }
       // Vs
       if (config.subpages?.vs === true) {
-        _.vs.source = load(topPage, path, 'vs', lang)
+        _.vs.source = load(topPage, path, 'vs', lang, sourceRoot)
       }
     }
   }

package/src/i18n/index.js

@@ -5,10 +5,12 @@ import homePageOverride from 'virtual:docsector-homepage-override'
 // @ Import language HJSON files (Vite-compatible eager import)
 const langModules = import.meta.glob('./languages/*.hjson', { eager: true })
 // @ Import markdown files (Vite-compatible eager import as raw strings)
-const mdModules = import.meta.glob('../pages/**/*.md', { eager: true, query: '?raw', import: 'default' })
+const currentMdModules = import.meta.glob('../pages/**/*.md', { eager: true, query: '?raw', import: 'default' })
+const oldMdModules = import.meta.glob('../pages/.old/**/*.md', { eager: true, query: '?raw', import: 'default' })
+const mdModules = { ...currentMdModules, ...oldMdModules }
 
 // @ Import pages
 import boot from 'pages/boot'
-import { books } from 'virtual:docsector-books'
+import { books, pageEntries } from 'virtual:docsector-books'
 
-export default buildMessages({ langModules, mdModules, books, boot, homePageOverride })
+export default buildMessages({ langModules, mdModules, books, pageEntries, boot, homePageOverride })

package/src/i18n/path.js

@@ -73,6 +73,19 @@ export function splitDotPathSegments (dotPath) {
   return normalized.split('.').filter(Boolean)
 }
 
+function splitI18nPathSegments (path) {
+  if (Array.isArray(path)) {
+    return normalizeSegments(path)
+  }
+
+  const normalized = String(path || '').trim()
+  if (normalized.includes('/')) {
+    return splitRoutePathSegments(normalized)
+  }
+
+  return splitDotPathSegments(normalized)
+}
+
 export function routeTitleI18nPath (routePath) {
   return buildI18nPath('_', ...splitRoutePathSegments(routePath), '_')
 }
@@ -82,11 +95,11 @@ export function routeSubpageSourceI18nPath (routePath, subpage = 'overview') {
 }
 
 export function pageTitleI18nPath (basePath) {
-  return buildI18nPath('_', ...splitDotPathSegments(basePath), '_')
+  return buildI18nPath('_', ...splitI18nPathSegments(basePath), '_')
 }
 
 export function pageValueI18nPath (absolutePath, key = 'source') {
-  return buildI18nPath('_', ...splitDotPathSegments(absolutePath), key)
+  return buildI18nPath('_', ...splitI18nPathSegments(absolutePath), key)
 }
 
 export function namespacedLabelI18nPath (book, nodePath) {

package/src/index.js

@@ -27,7 +27,7 @@
  * @param {string} config.branding.name - Project name displayed in sidebar
  * @param {string} config.branding.version - Version label
  * @param {string} [config.branding.description] - Project description (used in llms.txt)
- * @param {string[]} [config.branding.versions] - Available versions for dropdown
+ * @param {Array<string|Object>} [config.branding.versions] - Available versions for dropdown. Current docs keep unprefixed routes; archived versions can live in src/pages/.old/<version>/ and use /<version>/ route prefixes. Version objects may set released:false/status:'draft', status:'deprecated'/deprecated:true, or badge:{label,color,textColor} for selector badges.
  * @param {Object} config.links - External links
  * @param {string} [config.links.github] - GitHub repository URL
  * @param {string} [config.links.discussions] - GitHub discussions URL
@@ -111,7 +111,7 @@ export function createDocsector (config = {}) {
       logo: '/images/logo.png',
       name: 'My Project',
       version: 'v0.0.1',
-      versions: ['v0.0.1'],
+      versions: [{ id: 'v0.0.1', current: true, released: false }],
       ...config.branding
     },
 

package/src/layouts/DefaultLayout.vue

@@ -59,7 +59,7 @@ import { useMeta, colors } from 'quasar'
 
 import DMenu from '../components/DMenu.vue'
 import docsectorConfig from 'docsector.config.js'
-import { allBooks } from 'virtual:docsector-books'
+import { allBooks, booksByVersion } from 'virtual:docsector-books'
 import { pageTitleI18nPath } from '../i18n/path'
 
 defineOptions({ name: 'LayoutDefault' })
@@ -178,8 +178,20 @@ const getBookTabStyle = (book) => {
   }
 }
 
+const activeVersionId = computed(() => {
+  return route.matched?.[0]?.meta?.version ?? route.meta?.version ?? null
+})
+
+const activeVersionBooks = computed(() => {
+  if (activeVersionId.value && booksByVersion?.[activeVersionId.value]?.allBooks) {
+    return booksByVersion[activeVersionId.value].allBooks
+  }
+
+  return allBooks || []
+})
+
 const sortedBooks = computed(() => {
-  return [...(allBooks || [])]
+  return [...activeVersionBooks.value]
     .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
@@ -261,10 +273,12 @@ function openSettingsDialog () {
 
 function getFirstRoutePathByBook (bookId) {
   const routes = router.options?.routes || []
+  const versionId = activeVersionId.value
   let fallbackPath = null
 
   for (const topRoute of routes) {
     if (!topRoute || typeof topRoute.path !== 'string') continue
+    if (versionId && topRoute.meta?.version !== versionId) continue
     if ((topRoute.meta?.book ?? topRoute.meta?.type) !== bookId) continue
 
     const children = Array.isArray(topRoute.children) ? topRoute.children : []

package/src/pages/.old/v0.x/guide/getting-started.overview.en-US.md

@@ -0,0 +1,7 @@
+## Archived Version
+
+This page is a minimal archived `v0.x` fixture used to validate Docsector Reader version switching.
+
+## Current Behavior
+
+Selecting `v0.x` in the sidebar keeps the active book and page when an archived equivalent exists, then serves this Markdown from `src/pages/.old/v0.x`.

package/src/pages/.old/v0.x/guide/getting-started.overview.pt-BR.md

@@ -0,0 +1,7 @@
+## Versao Arquivada
+
+Esta pagina e um fixture minimo arquivado `v0.x` usado para validar a troca de versoes do Docsector Reader.
+
+## Comportamento Atual
+
+Ao selecionar `v0.x` no menu lateral, o leitor preserva o book e a pagina ativos quando existe um equivalente arquivado, entao serve este Markdown a partir de `src/pages/.old/v0.x`.

package/src/pages/.old/v0.x/guide.book.js

@@ -0,0 +1,12 @@
+import { defineBook } from '../../../index.js'
+
+export default defineBook({
+  id: 'guide',
+  label: 'Guide',
+  icon: 'history_edu',
+  order: 1,
+  color: {
+    active: 'white',
+    inactive: 'white'
+  }
+})

package/src/pages/.old/v0.x/guide.index.js

@@ -0,0 +1,28 @@
+export default {
+  '/getting-started': {
+    config: {
+      icon: 'history',
+      status: 'done',
+      meta: {
+        description: {
+          'en-US': 'Getting Started - Archived v0.x documentation of Docsector Reader',
+          'pt-BR': 'Comecando - Documentacao arquivada v0.x do Docsector Reader'
+        }
+      },
+      book: 'guide',
+      menu: {
+        header: {
+          icon: 'history_edu',
+          label: 'Archived v0.x'
+        }
+      },
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'Getting Started v0.x' },
+      'pt-BR': { title: 'Comecando v0.x' }
+    }
+  }
+}

package/src/pages/guide/configuration.overview.en-US.md

@@ -9,10 +9,17 @@ branding: {
   logo: '/images/logo.png',   // Path to logo in public/
   name: 'My Project',         // Project name shown in sidebar
   version: 'v1.0.0',          // Current version badge
-  versions: ['v1.0.0']        // Version dropdown options
+  versions: [
+    { id: 'v1.0.0', current: true, released: false },
+    { id: 'v0.x', released: true, status: 'deprecated' }
+  ] // Version dropdown options
 }
 ```
 
+The current version keeps unprefixed routes such as `/guide/getting-started/overview/`. Archived major versions can live under `src/pages/.old/&#123;version&#125;/` using the same book registry and Markdown layout, and are exposed at `/<version>/...`, for example `/v0.x/guide/getting-started/overview/`.
+
+Every version shows a release badge next to the version 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: &#123; label, color, textColor &#125;` to customize the badge.
+
 The `logo` path is relative to the `public/` folder. Recommended size: **85×85px**.
 
 ## Links
@@ -84,7 +91,11 @@ export default &#123;
     logo: '/images/logo.png',
     name: 'Acme Docs',
     version: 'v2.1.0',
-    versions: ['v2.1.0', 'v2.0.0', 'v1.0.0']
+    versions: [
+      &#123; id: 'v2.1.0', current: true, released: false &#125;,
+      &#123; id: 'v2.0.0', released: true &#125;,
+      &#123; id: 'v1.0.0', released: true, status: 'deprecated' &#125;
+    ]
   &#125;,
   links: &#123;
     github: 'https://github.com/acme/acme',

package/src/pages/guide/configuration.overview.pt-BR.md

@@ -9,10 +9,17 @@ branding: {
   logo: '/images/logo.png',   // Caminho do logo em public/
   name: 'Meu Projeto',        // Nome exibido na sidebar
   version: 'v1.0.0',          // Badge de versão atual
-  versions: ['v1.0.0']        // Opções do dropdown de versão
+  versions: [
+    { id: 'v1.0.0', current: true, released: false },
+    { id: 'v0.x', released: true, status: 'deprecated' }
+  ] // Opções do dropdown de versão
 }
 ```
 
+A versão atual mantém rotas sem prefixo, como `/guide/getting-started/overview/`. Versões major arquivadas podem ficar em `src/pages/.old/&#123;version&#125;/` usando o mesmo layout de book registry e Markdown, e são expostas em `/<version>/...`, por exemplo `/v0.x/guide/getting-started/overview/`.
+
+Toda versão mostra um badge de release ao lado da versão no seletor. Versões lançadas usam `released` por padrão; versões com `released: false` ou `status: 'draft'` usam `draft`; versões com `status: 'deprecated'` ou `deprecated: true` usam `deprecated` em vermelho. Use `badge: &#123; label, color, textColor &#125;` para customizar o badge.
+
 O caminho do `logo` é relativo à pasta `public/`. Tamanho recomendado: **85×85px**.
 
 ## Links
@@ -84,7 +91,11 @@ export default &#123;
     logo: '/images/logo.png',
     name: 'Acme Docs',
     version: 'v2.1.0',
-    versions: ['v2.1.0', 'v2.0.0', 'v1.0.0']
+    versions: [
+      &#123; id: 'v2.1.0', current: true, released: false &#125;,
+      &#123; id: 'v2.0.0', released: true &#125;,
+      &#123; id: 'v1.0.0', released: true, status: 'deprecated' &#125;
+    ]
   &#125;,
   links: &#123;
     github: 'https://github.com/acme/acme',

package/src/pages/guide/pages-and-routing.overview.en-US.md

@@ -83,3 +83,5 @@ Routes are automatically generated from the page registry. A page with path `/my
 - `/guide/my-page/overview` — Main content tab
 - `/guide/my-page/showcase` — Showcase tab (if enabled)
 - `/guide/my-page/vs` — Comparison tab (if enabled)
+
+Archived major versions use the same structure under `src/pages/.old/{version}/`. A page registered in `src/pages/.old/v0.x/guide.index.js` produces `/v0.x/guide/my-page/overview` while the current version remains `/guide/my-page/overview`.

package/src/pages/guide/pages-and-routing.overview.pt-BR.md

@@ -83,3 +83,5 @@ Rotas são geradas automaticamente a partir do registro de páginas. Uma página
 - `/guide/my-page/overview` — Aba de conteúdo principal
 - `/guide/my-page/showcase` — Aba de demonstração (se habilitada)
 - `/guide/my-page/vs` — Aba de comparação (se habilitada)
+
+Versões major arquivadas usam a mesma estrutura em `src/pages/.old/{version}/`. Uma página registrada em `src/pages/.old/v0.x/guide.index.js` produz `/v0.x/guide/my-page/overview`, enquanto a versão atual continua em `/guide/my-page/overview`.

package/src/pages/manual/components/d-menu.overview.en-US.md

@@ -26,7 +26,11 @@ Reads from `docsector.config.js`:
 - `branding.logo` — Project logo image
 - `branding.name` — Project name text
 - `branding.version` — Current version
-- `branding.versions` — Version dropdown options
+- `branding.versions` — Version dropdown options, including optional release badges
+
+The selector keeps current docs on unprefixed routes and switches archived versions to prefixed routes. For example, current `/guide/getting-started/overview/` can switch to archived `/v0.x/guide/getting-started/overview/` when a matching page exists under `src/pages/.old/v0.x/`.
+
+Every version object shows a badge after the version label. 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. The badge can be customized with `badge: { label, color, textColor }`.
 
 ## External Links
 
@@ -43,7 +47,7 @@ Each link is conditionally rendered — set to `null` in the config to hide:
 
 ## Page Tree
 
-The page tree is built from the router's routes at component creation time. Routes are grouped by their basepath (second URL segment). Groups with a `menu.header` configuration get an expansion panel with a sticky header.
+The page tree is built from the router's routes at component creation time. Routes are filtered by active version and book, then grouped by their page basepath. Groups with a `menu.header` configuration get an expansion panel with a sticky header.
 
 ## Menu Item Grouping
 

package/src/pages/manual/components/d-menu.overview.pt-BR.md

@@ -26,7 +26,11 @@ Lê do `docsector.config.js`:
 - `branding.logo` — Imagem do logo do projeto
 - `branding.name` — Texto do nome do projeto
 - `branding.version` — Versão atual
-- `branding.versions` — Opções do dropdown de versão
+- `branding.versions` — Opções do dropdown de versão, incluindo badges opcionais de release
+
+O seletor mantém a documentação atual em rotas sem prefixo e troca versões arquivadas para rotas prefixadas. Por exemplo, `/guide/getting-started/overview/` pode trocar para `/v0.x/guide/getting-started/overview/` quando existe uma página equivalente em `src/pages/.old/v0.x/`.
+
+Todo objeto de versão mostra um badge depois do label da versão. Versões lançadas usam `released` por padrão; versões com `released: false` ou `status: 'draft'` usam `draft`; versões com `status: 'deprecated'` ou `deprecated: true` usam `deprecated` em vermelho. O badge pode ser customizado com `badge: { label, color, textColor }`.
 
 ## Links Externos
 
@@ -43,7 +47,7 @@ Cada link é renderizado condicionalmente — defina como `null` no config para
 
 ## Árvore de Páginas
 
-A árvore de páginas é construída a partir das rotas do roteador no momento de criação do componente. Rotas são agrupadas pelo seu basepath (segundo segmento da URL). Grupos com configuração `menu.header` recebem um painel de expansão com header sticky.
+A árvore de páginas é construída a partir das rotas do roteador no momento de criação do componente. Rotas são filtradas pela versão e pelo book ativos, depois agrupadas pelo basepath da página. Grupos com configuração `menu.header` recebem um painel de expansão com header sticky.
 
 ## Agrupamento de Itens