@docsector/docsector-reader 2.0.6 → 2.1.0

package/README.md

@@ -68,6 +68,8 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🧬 **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
+- 🗃️ **Multi-Version History** — Archive older major versions under `src/pages/.old/<version>/` and expose them at prefixed routes (e.g. `/v0.x/guide/...`) while keeping the current docs at unprefixed routes
+- 🏷️ **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 }`
 - ⚙️ **Single Config File** — Customize branding, links, and languages via `docsector.config.js`
 
 ---
@@ -675,7 +677,10 @@ export default {
     logo: '/images/logo/my-logo.png',
     name: 'My Project',
     version: 'v1.0.0',
-    versions: ['v1.0.0', 'v0.9.0']
+    versions: [
+      { id: 'v1.0.0', current: true, released: false },
+      { id: 'v0.9.0', released: true, status: 'deprecated' }
+    ]
   },
 
   links: {
@@ -754,6 +759,10 @@ export default {
 }
 ```
 
+The current version keeps the normal unprefixed routes such as `/guide/getting-started/overview/`. Archived major versions can be placed under `src/pages/.old/<version>/` with the same book/index/Markdown layout, and are exposed with a URL prefix such as `/v0.x/guide/getting-started/overview/`.
+
+Every 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.
+
 ### MCP (optional)
 
 ```javascript
@@ -777,15 +786,17 @@ 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' })
+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 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 })
 ```
 
-> `books` is the preferred source because it preserves per-book registries and avoids path collisions when two books reuse the same route key.
+> `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.
 
 ### Language files
 

package/bin/docsector.js

@@ -23,7 +23,7 @@ const packageRoot = resolve(__dirname, '..')
 const args = process.argv.slice(2)
 const command = args[0]
 
-const VERSION = '2.0.6'
+const VERSION = '2.1.0'
 
 const HELP = `
   Docsector Reader v${VERSION}
@@ -105,7 +105,10 @@ export default {
   branding: {
     logo: '/images/logo.png',
     name: 'My Documentation',
-    version: 'v0.1.0'
+    version: 'v0.1.0',
+    versions: [
+      { id: 'v0.1.0', current: true, released: false }
+    ]
   },
 
   // @ Links
@@ -269,13 +272,15 @@ 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 { allPages as pages } from 'virtual:docsector-books'
+import { books, pageEntries } from 'virtual:docsector-books'
 
-export default buildMessages({ langModules, mdModules, pages, boot, homePageOverride })
+export default buildMessages({ langModules, mdModules, books, pageEntries, boot, homePageOverride })
 `
 
 const TEMPLATE_I18N_HJSON = `\

package/docsector.config.js

@@ -15,7 +15,19 @@ export default {
     // Project name displayed in the sidebar
     name: 'Docsector Reader',
     // Version label displayed next to the name
-    version: 'v' + pkg.version
+    version: 'v' + pkg.version,
+    versions: [
+      {
+        id: 'v' + pkg.version,
+        current: true,
+        released: false
+      },
+      {
+        id: 'v0.x',
+        released: true,
+        status: 'deprecated'
+      }
+    ]
   },
 
   // @ Links

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "2.0.6",
+  "version": "2.1.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/DMenu.vue

@@ -7,7 +7,7 @@ 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 { allBooks, booksByVersion, versions } from 'virtual:docsector-books'
 import { namespacedLabelI18nPath, routeSubpageSourceI18nPath } from '../i18n/path'
 
 const $q = useQuasar()
@@ -20,19 +20,93 @@ const links = docsectorConfig.links || {}
 
 const term = ref(null)
 const founds = ref(false)
-const version = ref(branding.version || 'v0.x')
-const versions = ref(branding.versions || ['v0.x'])
 const items = ref([])
 const scrolling = ref(null)
 
 const subpage = computed(() => {
   const parent = $route.matched[0]?.path
   const child = $route.matched[1]?.path
+  if (!parent || !child) return '/overview'
   return child.substring(parent.length)
 })
 
+const activeVersionId = computed(() => {
+  return $route.matched?.[0]?.meta?.version ?? versions?.[0]?.id ?? ''
+})
+
+const activeBooks = computed(() => {
+  if (activeVersionId.value && booksByVersion?.[activeVersionId.value]?.allBooks) {
+    return booksByVersion[activeVersionId.value].allBooks
+  }
+
+  return allBooks || []
+})
+
+const draftReleaseStatuses = new Set(['draft', 'unreleased', 'preview', 'next'])
+
+const normalizeVersionBadge = (item) => {
+  const configuredStatus = item.deprecated === true
+    ? 'deprecated'
+    : (item.releaseStatus || item.status)
+  const explicitlyReleased = item.released !== undefined ? item.released !== false : null
+  const released = configuredStatus === 'deprecated'
+    ? true
+    : (explicitlyReleased ?? !draftReleaseStatuses.has(String(configuredStatus || '').toLowerCase()))
+  const releaseStatus = configuredStatus || (released ? 'released' : 'draft')
+  const rawBadge = item.badge ?? item.releaseBadge
+  const deprecated = releaseStatus === 'deprecated'
+  const defaultColor = deprecated ? 'negative' : (released ? 'positive' : 'warning')
+  const defaultTextColor = (deprecated || released) ? 'white' : 'dark'
+
+  if (rawBadge === false || rawBadge === null) {
+    return { label: releaseStatus, color: defaultColor, textColor: defaultTextColor }
+  }
+
+  if (typeof rawBadge === 'string') {
+    return { label: rawBadge, color: defaultColor, textColor: defaultTextColor }
+  }
+
+  if (typeof rawBadge === 'object' && rawBadge !== null) {
+    const label = rawBadge.label || rawBadge.text || releaseStatus
+    if (!label) {
+      return null
+    }
+
+    return {
+      ...rawBadge,
+      label,
+      color: rawBadge.color || defaultColor,
+      textColor: rawBadge.textColor || defaultTextColor
+    }
+  }
+
+  return { label: releaseStatus, color: defaultColor, textColor: defaultTextColor }
+}
+
+const versionOptions = computed(() => {
+  return (versions || [])
+    .filter(item => item && item.id)
+    .map(item => ({
+      label: item.label || item.id,
+      value: item.id,
+      badge: normalizeVersionBadge(item),
+      released: item.released !== false,
+      deprecated: item.deprecated === true || item.releaseStatus === 'deprecated' || item.status === 'deprecated',
+      releaseStatus: item.releaseStatus || item.status || (item.released === false ? 'draft' : 'released')
+    }))
+})
+
+const activeVersionOption = computed(() => {
+  return versionOptions.value.find(item => item.value === activeVersionId.value) || null
+})
+
+const version = computed({
+  get: () => activeVersionId.value,
+  set: (versionId) => onVersionChange(versionId)
+})
+
 const defaultBookId = computed(() => {
-  const sortedBooks = [...(allBooks || [])]
+  const sortedBooks = [...activeBooks.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
@@ -52,13 +126,97 @@ const currentBookId = computed(() => {
   return defaultBookId.value
 })
 
+const normalizeRoutePath = (path) => {
+  const normalized = String(path || '').trim()
+  if (normalized === '' || normalized === '/') {
+    return '/'
+  }
+
+  const sanitized = normalized.replace(/\/+$/, '')
+  return sanitized === '' ? '/' : sanitized
+}
+
+const getTopRoutes = () => {
+  return ($router.options.routes || []).slice(0, -2)
+}
+
+const routeHasSubpage = (route, subpageName) => {
+  return (route.children || []).some(child => child.path === subpageName)
+}
+
+const routeToSubpagePath = (route, subpageName) => {
+  return `${route.path.replace(/\/$/, '')}/${subpageName}/`
+}
+
+const getCurrentSubpageName = () => {
+  return String(subpage.value || '/overview').replace(/^\/+|\/+$/g, '') || 'overview'
+}
+
+const getFirstRoutePathByVersion = (versionId, preferredBook = null) => {
+  const routes = getTopRoutes()
+
+  for (const preferBook of [preferredBook, null]) {
+    for (const route of routes) {
+      if (route?.meta?.version !== versionId) continue
+      if (preferBook && (route.meta?.book ?? route.meta?.type) !== preferBook) continue
+      if (!routeHasSubpage(route, 'overview')) continue
+
+      const hasInternalLink = typeof route.meta?.link?.to === 'string' && route.meta.link.to.trim().length > 0
+      if (hasInternalLink) continue
+
+      return routeToSubpagePath(route, 'overview')
+    }
+  }
+
+  return '/'
+}
+
+const getEquivalentRoutePath = (versionId) => {
+  const routeMeta = $route.matched?.[0]?.meta || {}
+  const book = routeMeta.book ?? routeMeta.type ?? currentBookId.value
+  const pagePath = routeMeta.pagePath
+  const subpageName = getCurrentSubpageName()
+
+  if (book && typeof pagePath === 'string') {
+    const equivalentRoute = getTopRoutes().find(route => {
+      return route?.meta?.version === versionId &&
+        (route.meta?.book ?? route.meta?.type) === book &&
+        route.meta?.pagePath === pagePath &&
+        routeHasSubpage(route, subpageName)
+    })
+
+    if (equivalentRoute) {
+      return routeToSubpagePath(equivalentRoute, subpageName)
+    }
+  }
+
+  return getFirstRoutePathByVersion(versionId, book)
+}
+
+function onVersionChange (versionId) {
+  if (!versionId || versionId === activeVersionId.value) return
+
+  const targetVersion = (versions || []).find(item => item.id === versionId)
+  if (!targetVersion) return
+
+  if (typeof targetVersion.url === 'string' && targetVersion.url.trim().length > 0) {
+    openURL(targetVersion.url)
+    return
+  }
+
+  const targetPath = getEquivalentRoutePath(versionId)
+  if (normalizeRoutePath($route.path) !== normalizeRoutePath(targetPath)) {
+    $router.push(targetPath)
+  }
+}
+
 const searchTerm = (term) => {
   if (term.length > 1) {
     term = term.toLowerCase()
     const locale = $q.localStorage.getItem('setting.language')
     founds.value = []
 
-    for (const [index, group] of items.value.entries()) {
+    for (const group of items.value) {
       searchTermIterate(group, term, locale)
     }
   } else {
@@ -74,13 +232,14 @@ const searchTermIterate = (items, term, locale) => {
   } else if (typeof items === 'object') {
     const item = items
     const path = item.path
+    const tagPath = item.meta?.unversionedPath || path
     founds.value[path] = false
 
     // @ search in i18n/tags.hjson
     if (tags[locale] && Object.keys(tags[locale]).length > 0) {
-      founds.value[path] = tags[locale][path]?.indexOf(term) !== -1
+      founds.value[path] = tags[locale][tagPath]?.indexOf(term) !== -1
       if (founds.value[path] === false && locale !== 'en-US') {
-        founds.value[path] = tags['en-US'][path]?.indexOf(term) !== -1
+        founds.value[path] = tags['en-US'][tagPath]?.indexOf(term) !== -1
       }
     }
 
@@ -181,11 +340,13 @@ onBeforeUnmount(() => {
 })
 
 const buildMenuItems = () => {
-  const routes = ($router.options.routes || []).slice(0, -2) // Delete last 2 routes
+  const routes = getTopRoutes()
   const activeBook = currentBookId.value
+  const activeVersion = activeVersionId.value
 
   const filteredRoutes = routes.filter(route => {
     const routeBook = route?.meta?.book ?? route?.meta?.type
+    if (activeVersion && route?.meta?.version !== activeVersion) return false
     if (!activeBook) return true
     return routeBook === activeBook
   })
@@ -201,7 +362,7 @@ const buildMenuItems = () => {
     })
 
     // # Route
-    const basepath = route.path.split('/')[2]
+  const basepath = route.meta?.menuGroupPath || route.path.split('/')[2]
     const header = route.meta?.menu?.header
 
     if (header !== undefined && basepath !== nodeBasepath) {
@@ -227,7 +388,7 @@ const rebuildItems = () => {
 }
 
 rebuildItems()
-watch(currentBookId, rebuildItems)
+watch([currentBookId, activeVersionId], rebuildItems)
 </script>
 
 <template>
@@ -254,10 +415,44 @@ watch(currentBookId, rebuildItems)
       <div class="text-weight-medium">{{ branding.name || 'Docsector' }}</div>
       <div class="text-caption q-pt-xs">{{ t('system.documentation') }}</div>
       <q-select class="q-mr-md"
-        v-model="version" :options="versions"
+        v-model="version" :options="versionOptions"
+        emit-value map-options
         dense options-dense
         behavior="menu"
-      />
+      >
+        <template v-slot:selected>
+          <div v-if="activeVersionOption" class="version-select-option">
+            <span class="version-select-label">{{ activeVersionOption.label }}</span>
+            <q-badge
+              v-if="activeVersionOption.badge"
+              class="version-select-badge"
+              :color="activeVersionOption.badge.color || 'warning'"
+              :text-color="activeVersionOption.badge.textColor || 'dark'"
+              :outline="activeVersionOption.badge.outline === true"
+            >
+              {{ activeVersionOption.badge.label }}
+            </q-badge>
+          </div>
+        </template>
+        <template v-slot:option="scope">
+          <q-item v-bind="scope.itemProps">
+            <q-item-section>
+              <div class="version-select-option">
+                <span class="version-select-label">{{ scope.opt.label }}</span>
+                <q-badge
+                  v-if="scope.opt.badge"
+                  class="version-select-badge"
+                  :color="scope.opt.badge.color || 'warning'"
+                  :text-color="scope.opt.badge.textColor || 'dark'"
+                  :outline="scope.opt.badge.outline === true"
+                >
+                  {{ scope.opt.badge.label }}
+                </q-badge>
+              </div>
+            </q-item-section>
+          </q-item>
+        </template>
+      </q-select>
     </div>
   </div>
 
@@ -470,6 +665,23 @@ body.body--light
       width: 30px
       height: 3px
 
+.version-select-option
+  display: flex
+  align-items: center
+  gap: 6px
+  min-width: 0
+  max-width: 100%
+
+.version-select-label
+  overflow: hidden
+  text-overflow: ellipsis
+  white-space: nowrap
+
+.version-select-badge
+  flex: 0 0 auto
+  font-size: 10px
+  line-height: 1
+
 // Search
 label[for="search"]
   z-index: 2

package/src/components/DPageBar.vue

@@ -37,6 +37,11 @@ const subpage = computed(() => {
 })
 
 const fileKey = computed(() => {
+  const sourcePathBase = route.matched?.[0]?.meta?.sourcePathBase
+  if (typeof sourcePathBase === 'string' && sourcePathBase.length > 0) {
+    return `${sourcePathBase}.${subpage.value}.${locale.value}.md`
+  }
+
   const base = store.state.page.base
   if (!base) return ''
   return `${base}.${subpage.value}.${locale.value}.md`

package/src/components/DPageMeta.vue

@@ -20,7 +20,17 @@ function normalizeEditBaseUrl (url = '') {
 
 const base = normalizeEditBaseUrl(docsectorConfig.github?.editBaseUrl || '')
 
+function getCurrentSubpageName () {
+  const relative = store.state.page.relative || '/overview'
+  return String(relative).replace(/^\/+|\/+$/g, '') || 'overview'
+}
+
 function routePathToSourcePath (path = '') {
+  const sourcePathBase = route.matched?.[0]?.meta?.sourcePathBase
+  if (typeof sourcePathBase === 'string' && sourcePathBase.length > 0) {
+    return `/${sourcePathBase}.${getCurrentSubpageName()}`
+  }
+
   const cleanPath = String(path)
     .replace(/\/index\.html$/, '')
     .replace(/\/+$/, '')
@@ -131,34 +141,38 @@ const languages = computed(() => {
   return `${i18nLocalesAvailable}/${i18nLocales.length}`
 })
 
-const prev = computed(() => {
-  const base = store.state.page.base
-  const routes = router.options.routes.slice(0, -2)
-
-  for (let i = 0; i < routes.length; i++) {
-    if ('/' + base === routes[i].path) {
-      if (i > 0) {
-        return routes[i - 1].path
-      }
-    }
+const normalizeRoutePath = (path) => {
+  const normalized = String(path || '').trim()
+  if (normalized === '' || normalized === '/') {
+    return '/'
   }
 
-  return ''
+  const sanitized = normalized.replace(/\/+$/, '')
+  return sanitized === '' ? '/' : sanitized
+}
+
+const getVersionSiblingPath = (offset) => {
+  const versionId = route.matched?.[0]?.meta?.version ?? null
+  const currentPath = normalizeRoutePath(route.matched?.[0]?.path || `/${store.state.page.base}`)
+  const routes = router.options.routes
+    .slice(0, -2)
+    .filter(item => !versionId || item?.meta?.version === versionId)
+
+  const index = routes.findIndex(item => normalizeRoutePath(item.path) === currentPath)
+  if (index < 0) return ''
+
+  const sibling = routes[index + offset]
+  if (!sibling) return ''
+
+  return sibling.path
+}
+
+const prev = computed(() => {
+  return getVersionSiblingPath(-1)
 })
 
 const next = computed(() => {
-  const base = store.state.page.base
-  const routes = router.options.routes.slice(0, -2)
-
-  for (let i = 0; i < routes.length; i++) {
-    if ('/' + base === routes[i].path) {
-      if (typeof routes[i + 1] !== 'undefined') {
-        return routes[i + 1].path
-      }
-    }
-  }
-
-  return ''
+  return getVersionSiblingPath(1)
 })
 
 const hideRemoteHomeFooterMeta = computed(() => {

package/src/css/app.sass

@@ -179,7 +179,7 @@ body.body--dark
     margin: 0.3em 0 0.1em
 
   code:not(pre > code)
-    padding: 3px 5px
+    padding: 1px 3px
     margin: 0 2px
     border-radius: 2px
     white-space: normal
@@ -288,6 +288,7 @@ body.body--dark
       overflow-x: auto
       -webkit-overflow-scrolling: touch
       max-width: 100%
+      margin-bottom: 10px
     table
       width: max-content
       border: 1px solid #eee