@docsector/docsector-reader 0.6.0 → 0.7.1

package/README.md

@@ -23,6 +23,8 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 📝 **Markdown Rendering** — Write docs in Markdown, rendered with syntax highlighting (Prism.js)
 - 🧩 **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]`
+- 🤖 **AI-Friendly** — "Copy page" button copies raw Markdown for LLMs; "View as Markdown" opens any page as plain text via `.md` URL suffix
+- 📅 **Last Updated Date** — Automatic per-page "last updated" date from git commit history, locale-formatted
 - 🌍 **Internationalization (i18n)** — Multi-language support with HJSON locale files and per-page translations
 - 🌗 **Dark/Light Mode** — Automatic theme switching with Quasar Dark Plugin
 - 🔗 **Anchor Navigation** — Right-side Table of Contents tree with scroll tracking

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "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/DPageBar.vue

@@ -0,0 +1,135 @@
+<script setup>
+import { ref, computed } from 'vue'
+import { useRoute } from 'vue-router'
+import { useStore } from 'vuex'
+import { useI18n } from 'vue-i18n'
+import { copyToClipboard, openURL } from 'quasar'
+
+import gitDates from 'virtual:docsector-git-dates'
+
+const store = useStore()
+const route = useRoute()
+const { t, locale } = useI18n()
+
+const copied = ref(false)
+
+const subpage = computed(() => {
+  const rel = store.state.page.relative
+  return rel ? rel.replace(/^\//, '') : 'overview'
+})
+
+const fileKey = computed(() => {
+  const base = store.state.page.base
+  if (!base) return ''
+  return `${base}.${subpage.value}.${locale.value}.md`
+})
+
+const formattedDate = computed(() => {
+  const iso = gitDates[fileKey.value]
+  if (!iso) return ''
+
+  const date = new Date(iso)
+  if (isNaN(date.getTime())) return ''
+
+  return new Intl.DateTimeFormat(locale.value, {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric'
+  }).format(date)
+})
+
+const rawMarkdown = computed(() => {
+  const absolute = store.state.i18n.absolute
+  if (!absolute) return ''
+
+  const source = t(`_.${absolute}.source`)
+  if (!source) return ''
+
+  return String(source)
+    .replace(/&#123;/g, '{')
+    .replace(/&#125;/g, '}')
+    .replace(/\{'([^']+)'\}/g, '$1')
+    .replace(/&amp;/g, '&')
+})
+
+const markdownURL = computed(() => {
+  return `${route.path}.md`
+})
+
+const copyPage = () => {
+  if (!rawMarkdown.value) return
+
+  copyToClipboard(rawMarkdown.value).then(() => {
+    copied.value = true
+    setTimeout(() => { copied.value = false }, 2000)
+  })
+}
+
+const viewAsMarkdown = () => {
+  openURL(markdownURL.value)
+}
+</script>
+
+<template>
+<div class="d-page-bar">
+  <span v-if="formattedDate" class="d-page-bar__date">
+    {{ t('page.lastUpdated') }}: {{ formattedDate }}
+  </span>
+  <span v-else class="d-page-bar__date"></span>
+
+  <q-btn-dropdown
+    class="d-page-bar__actions"
+    split
+    no-caps
+    :icon="copied ? 'check' : 'content_copy'"
+    :label="copied ? t('page.copied') : t('page.copyPage')"
+    :color="copied ? 'positive' : 'grey-7'"
+    size="sm"
+    @click="copyPage"
+  >
+    <q-list style="min-width: 240px">
+      <q-item clickable v-close-popup @click="copyPage" class="q-py-sm">
+        <q-item-section avatar>
+          <q-icon name="content_copy" />
+        </q-item-section>
+        <q-item-section>
+          <q-item-label>{{ t('page.copyPage') }}</q-item-label>
+          <q-item-label caption>{{ t('page.copyPageCaption') }}</q-item-label>
+        </q-item-section>
+      </q-item>
+
+      <q-item clickable v-close-popup @click="viewAsMarkdown" class="q-py-sm">
+        <q-item-section avatar>
+          <q-icon name="description" />
+        </q-item-section>
+        <q-item-section>
+          <q-item-label>{{ t('page.viewAsMarkdown') }}</q-item-label>
+          <q-item-label caption>{{ t('page.viewAsMarkdownCaption') }}</q-item-label>
+        </q-item-section>
+        <q-item-section side>
+          <q-icon name="open_in_new" size="xs" />
+        </q-item-section>
+      </q-item>
+    </q-list>
+  </q-btn-dropdown>
+</div>
+</template>
+
+<style lang="sass">
+.d-page-bar
+  display: flex
+  justify-content: space-between
+  align-items: center
+  margin-bottom: 4px
+
+  &__date
+    font-size: 0.8rem
+    opacity: 0.6
+
+  &__actions
+    font-size: 0.75rem
+
+body.body--dark
+  .d-page-bar__date
+    color: rgba(255, 255, 255, 0.7)
+</style>

package/src/components/DSubpage.vue

@@ -3,6 +3,7 @@ import { computed } from 'vue'
 import { useRoute } from 'vue-router'
 // components
 import DPage from "./DPage.vue";
+import DPageBar from "./DPageBar.vue";
 import DH1 from "./DH1.vue";
 import DPageSection from "./DPageSection.vue";
 
@@ -23,6 +24,8 @@ const id = computed(() => {
 <template>
 <d-page>
   <header>
+    <d-page-bar />
+    <hr />
     <d-h1 :id="0" />
   </header>
 

package/src/i18n/helpers.js

@@ -16,6 +16,51 @@
  *   export default buildMessages({ langModules, mdModules, pages, boot })
  */
 
+/**
+ * Engine default i18n keys, keyed by locale.
+ * These are deep-merged into consumer messages so engine components
+ * always have their required translations available.
+ */
+const engineDefaults = {
+  'en-US': {
+    page: {
+      lastUpdated: 'Last updated',
+      copyPage: 'Copy page',
+      copyPageCaption: 'Copy page as Markdown for LLMs',
+      copied: 'Copied!',
+      viewAsMarkdown: 'View as Markdown',
+      viewAsMarkdownCaption: 'View this page as plain text'
+    }
+  },
+  'pt-BR': {
+    page: {
+      lastUpdated: 'Última atualização',
+      copyPage: 'Copiar página',
+      copyPageCaption: 'Copiar página como Markdown para LLMs',
+      copied: 'Copiado!',
+      viewAsMarkdown: 'Ver como Markdown',
+      viewAsMarkdownCaption: 'Ver esta página como texto simples'
+    }
+  }
+}
+
+/**
+ * Deep-merge source into target (target values take precedence).
+ */
+function deepMerge (target, source) {
+  for (const key of Object.keys(source)) {
+    if (
+      source[key] && typeof source[key] === 'object' && !Array.isArray(source[key]) &&
+      target[key] && typeof target[key] === 'object' && !Array.isArray(target[key])
+    ) {
+      deepMerge(target[key], source[key])
+    } else if (!(key in target)) {
+      target[key] = source[key]
+    }
+  }
+  return target
+}
+
 /**
  * Escape characters that conflict with vue-i18n message syntax.
  *
@@ -77,6 +122,11 @@ export function buildMessages ({ langModules, mdModules, pages, boot, langs }) {
     const langKey = `./languages/${lang}.hjson`
     i18n[lang] = langModules[langKey]?.default || langModules[langKey] || {}
 
+    // Merge engine defaults (consumer values take precedence)
+    if (engineDefaults[lang]) {
+      deepMerge(i18n[lang], engineDefaults[lang])
+    }
+
     // @ Iterate pages
     for (const [key, page] of Object.entries(pages)) {
       const path = key.slice(1)

package/src/i18n/languages/en-US.hjson

@@ -30,7 +30,13 @@
     nav: {
       prev: 'Previous page',
       next: 'Next page'
-    }
+    },
+    lastUpdated: 'Last updated',
+    copyPage: 'Copy page',
+    copyPageCaption: 'Copy page as Markdown for LLMs',
+    copied: 'Copied!',
+    viewAsMarkdown: 'View as Markdown',
+    viewAsMarkdownCaption: 'View this page as plain text'
   },
 
   menu: {

package/src/i18n/languages/pt-BR.hjson

@@ -29,7 +29,13 @@
     nav: {
       prev: 'Página anterior',
       next: 'Próxima página'
-    }
+    },
+    lastUpdated: 'Última atualização',
+    copyPage: 'Copiar página',
+    copyPageCaption: 'Copiar página como Markdown para LLMs',
+    copied: 'Copiado!',
+    viewAsMarkdown: 'Ver como Markdown',
+    viewAsMarkdownCaption: 'Ver esta página como texto simples'
   },
 
   menu: {

package/src/quasar.factory.js

@@ -23,7 +23,8 @@
  * @param {Function} [options.extendViteConf] - Additional Vite config extension
  */
 
-import { readFileSync, existsSync, rmSync, mkdirSync, writeFileSync } from 'fs'
+import { readFileSync, existsSync, rmSync, mkdirSync, writeFileSync, readdirSync } from 'fs'
+import { execSync } from 'child_process'
 import { createHash } from 'crypto'
 import { resolve } from 'path'
 import { pathToFileURL } from 'url'
@@ -231,6 +232,193 @@ function createPrerenderMetaPlugin (projectRoot) {
   }
 }
 
+/**
+ * Create a Vite plugin that collects git last-commit dates for all Markdown
+ * files under src/pages/ and exposes them as a virtual module.
+ *
+ * Consuming components can `import gitDates from 'virtual:docsector-git-dates'`
+ * to get an object mapping relative page keys to ISO date strings.
+ *
+ * Keys use the pattern: `<type>/<path>.<subpage>.<locale>.md`
+ * e.g. `manual/Bootgly/about/what.overview.en-US.md`
+ */
+function createGitDatesPlugin (projectRoot) {
+  const virtualId = 'virtual:docsector-git-dates'
+  const resolvedId = '\0' + virtualId
+  let dates = {}
+
+  function collectDates () {
+    dates = {}
+    const pagesDir = resolve(projectRoot, 'src', 'pages')
+    if (!existsSync(pagesDir)) return
+
+    const walkDir = (dir) => {
+      const entries = readdirSync(dir, { withFileTypes: true })
+      for (const entry of entries) {
+        const fullPath = resolve(dir, entry.name)
+        if (entry.isDirectory()) {
+          walkDir(fullPath)
+        } else if (entry.name.endsWith('.md')) {
+          try {
+            const date = execSync(
+              `git log -1 --format=%cI -- "${fullPath}"`,
+              { cwd: projectRoot, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+            ).trim()
+            if (date) {
+              // Key relative to src/pages/, e.g. "manual/Bootgly/about/what.overview.en-US.md"
+              const relKey = fullPath.slice(pagesDir.length + 1)
+              dates[relKey] = date
+            }
+          } catch {
+            // git not available or file untracked — skip
+          }
+        }
+      }
+    }
+
+    walkDir(pagesDir)
+  }
+
+  return {
+    name: 'docsector-git-dates',
+    buildStart () {
+      collectDates()
+    },
+    resolveId (id) {
+      if (id === virtualId) return resolvedId
+    },
+    load (id) {
+      if (id === resolvedId) {
+        return `export default ${JSON.stringify(dates)}`
+      }
+    }
+  }
+}
+
+/**
+ * Create a Vite plugin that serves raw Markdown content for `.md` suffixed URLs.
+ *
+ * In **dev mode**, intercepts requests like `/manual/Bootgly/about/what/overview.md`
+ * and serves the corresponding `src/pages/manual/Bootgly/about/what.overview.<lang>.md`
+ * file as `text/plain; charset=utf-8`.
+ *
+ * In **production build** (`closeBundle`), generates static `.md` files in `dist/spa/`
+ * for each page/subpage so that the `.md` URLs resolve to actual files on any static host.
+ *
+ * The language served is determined by the `?lang=` query parameter, falling back to the
+ * `defaultLanguage` from `docsector.config.js`.
+ */
+function createMarkdownEndpointPlugin (projectRoot) {
+  const pagesDir = resolve(projectRoot, 'src', 'pages')
+
+  function resolveMarkdownFile (urlPath, lang) {
+    // URL: /manual/Bootgly/about/what/overview.md
+    // Strip leading slash and trailing .md
+    const clean = urlPath.replace(/^\//, '').replace(/\.md$/, '')
+    // Split into segments: ['manual', 'Bootgly', 'about', 'what', 'overview']
+    const segments = clean.split('/')
+    if (segments.length < 2) return null
+
+    // Last segment is the subpage (overview, showcase, vs)
+    const subpage = segments.pop()
+    // Remaining segments form the type + path: 'manual/Bootgly/about/what'
+    const basePath = segments.join('/')
+
+    // File: src/pages/manual/Bootgly/about/what.overview.en-US.md
+    const filePath = resolve(pagesDir, `${basePath}.${subpage}.${lang}.md`)
+    if (existsSync(filePath)) return filePath
+
+    return null
+  }
+
+  return {
+    name: 'docsector-markdown-endpoint',
+
+    configureServer (server) {
+      // Read default language from config
+      let defaultLang = 'en-US'
+      try {
+        const configPath = resolve(projectRoot, 'docsector.config.js')
+        if (existsSync(configPath)) {
+          // Dynamic import in dev — we read it synchronously via a simple approach
+          const configContent = readFileSync(configPath, 'utf-8')
+          const match = configContent.match(/defaultLanguage\s*:\s*['"]([^'"]+)['"]/)
+          if (match) defaultLang = match[1]
+        }
+      } catch { /* use fallback */ }
+
+      server.middlewares.use((req, res, next) => {
+        const url = new URL(req.url, 'http://localhost')
+        if (!url.pathname.endsWith('.md')) return next()
+
+        const lang = url.searchParams.get('lang') || defaultLang
+        const file = resolveMarkdownFile(url.pathname, lang)
+        if (!file) return next()
+
+        const content = readFileSync(file, 'utf-8')
+        res.setHeader('Content-Type', 'text/plain; charset=utf-8')
+        res.end(content)
+      })
+    },
+
+    apply: 'serve'
+  }
+}
+
+/**
+ * Create a Vite plugin that generates static `.md` files at build time.
+ *
+ * Runs in the `closeBundle` hook alongside the prerender-meta plugin.
+ * For each page/subpage, copies the raw Markdown source into
+ * `dist/spa/<routePath>.md` so that `.md` URLs work on static hosts.
+ */
+function createMarkdownBuildPlugin (projectRoot) {
+  return {
+    name: 'docsector-markdown-build',
+    apply: 'build',
+    async closeBundle () {
+      const distDir = resolve(projectRoot, 'dist', 'spa')
+      if (!existsSync(distDir)) return
+
+      const pagesDir = resolve(projectRoot, 'src', 'pages')
+      const configUrl = pathToFileURL(resolve(projectRoot, 'docsector.config.js')).href
+      const pagesUrl = pathToFileURL(resolve(projectRoot, 'src', 'pages', 'index.js')).href
+
+      const { default: config } = await import(configUrl)
+      const { default: pages } = await import(pagesUrl)
+
+      const defaultLang = config.defaultLanguage || config.languages?.[0]?.value || 'en-US'
+      let count = 0
+
+      for (const [pagePath, page] of Object.entries(pages)) {
+        if (page.config === null) continue
+        if (page.config.status === 'empty') continue
+
+        const type = page.config.type ?? 'manual'
+
+        const subpages = ['overview']
+        if (page.config.subpages?.showcase) subpages.push('showcase')
+        if (page.config.subpages?.vs) subpages.push('vs')
+
+        for (const subpage of subpages) {
+          const srcFile = resolve(pagesDir, `${type}${pagePath}.${subpage}.${defaultLang}.md`)
+          if (!existsSync(srcFile)) continue
+
+          const routePath = `${type}${pagePath}/${subpage}`
+          const destFile = resolve(distDir, `${routePath}.md`)
+          const destDir = resolve(destFile, '..')
+
+          mkdirSync(destDir, { recursive: true })
+          writeFileSync(destFile, readFileSync(srcFile, 'utf-8'))
+          count++
+        }
+      }
+
+      console.log(`\x1b[36m[docsector]\x1b[0m Generated ${count} static .md files`)
+    }
+  }
+}
+
 /**
  * Create a complete Quasar configuration for a docsector-reader consumer project.
  *
@@ -301,6 +489,9 @@ export function createQuasarConfig (options = {}) {
 
       vitePlugins: [
         createHjsonPlugin(),
+        createGitDatesPlugin(projectRoot),
+        createMarkdownEndpointPlugin(projectRoot),
+        createMarkdownBuildPlugin(projectRoot),
         createPagesWatchPlugin(projectRoot),
         createPrerenderMetaPlugin(projectRoot),
         ...vitePlugins