@docsector/docsector-reader 0.13.0 → 1.0.0

package/README.md

@@ -46,6 +46,8 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - ✏️ **Edit on GitHub** — Direct links to edit pages on your repository
 - 📅 **Last Updated Date** — Automatic per-page "last updated" date from git commit history, locale-formatted
 - 📊 **Translation Progress** — Automatic translation percentage based on header coverage
+- 🏠 **Markdown Home at Root** — Homepage is rendered from `src/pages/Homepage.{lang}.md` directly at `/`
+- 🧭 **Quick Links Custom Element** — Use `<d-quick-links>` and `<d-quick-link>` in Markdown to render rich home navigation cards
 - ⚙️ **Single Config File** — Customize branding, links, and languages via `docsector.config.js`
 
 ---

package/bin/docsector.js

@@ -23,7 +23,7 @@ const packageRoot = resolve(__dirname, '..')
 const args = process.argv.slice(2)
 const command = args[0]
 
-const VERSION = '0.13.0'
+const VERSION = '1.0.0'
 
 const HELP = `
   Docsector Reader v${VERSION}
@@ -341,6 +341,22 @@ export default {
 }
 `
 
+const TEMPLATE_HOMEPAGE_MD = `\
+# Welcome to Docsector Reader
+
+Docsector Reader is a markdown-first documentation engine.
+
+## Quick Links
+
+- [Getting Started](/guide/getting-started/overview/)
+- [Configuration](/guide/configuration/overview/)
+- [Pages and Routing](/guide/pages-and-routing/overview/)
+
+## About
+
+- Repository: [docsector/docsector-reader](https://github.com/docsector/docsector-reader)
+`
+
 const TEMPLATE_BOOT_PAGE = `\
 <template>
 <q-page-container>
@@ -703,6 +719,18 @@ npm-debug.log*
 .thumbs.db
 `
 
+const TEMPLATE_MARKDOWNLINT = `\
+{
+  "MD013": false,
+  "MD033": {
+    "allowed_elements": [
+      "d-quick-links",
+      "d-quick-link"
+    ]
+  }
+}
+`
+
 const TEMPLATE_ROBOTS_TXT = `\
 User-agent: *
 Allow: /
@@ -822,9 +850,11 @@ 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/boot.js\` | Boot metadata for the home page |
-| \`src/pages/@/\` | Special pages (Home, 404) |
+| \`src/pages/Homepage.en-US.md\` | Home page content in Markdown |
+| \`src/pages/404Page.vue\` | Not found page |
 | \`src/pages/guide/\` | Guide pages (Markdown files) |
 | \`src/i18n/languages/\` | Translation files (HJSON format) |
 | \`src/css/app.sass\` | Custom styles |
@@ -927,7 +957,6 @@ function initProject (name) {
     'src/i18n',
     'src/i18n/languages',
     'src/pages',
-    'src/pages/@',
     'src/pages/guide',
     'public',
     'public/images',
@@ -944,6 +973,7 @@ function initProject (name) {
     ['package.json', getTemplatePackageJson(name)],
     ['quasar.config.js', TEMPLATE_QUASAR_CONFIG],
     ['docsector.config.js', TEMPLATE_DOCSECTOR_CONFIG],
+    ['.markdownlint.json', TEMPLATE_MARKDOWNLINT],
     ['index.html', TEMPLATE_INDEX_HTML],
     ['postcss.config.cjs', TEMPLATE_POSTCSS],
     ['.gitignore', TEMPLATE_GITIGNORE],
@@ -953,8 +983,8 @@ function initProject (name) {
     ['src/i18n/languages/en-US.hjson', TEMPLATE_I18N_HJSON],
     ['src/pages/index.js', TEMPLATE_PAGES_INDEX],
     ['src/pages/boot.js', TEMPLATE_PAGES_BOOT],
-    ['src/pages/@/BootPage.vue', TEMPLATE_BOOT_PAGE],
-    ['src/pages/@/404Page.vue', TEMPLATE_404_PAGE],
+    ['src/pages/Homepage.en-US.md', TEMPLATE_HOMEPAGE_MD],
+    ['src/pages/404Page.vue', TEMPLATE_404_PAGE],
     ['src/pages/guide/getting-started.overview.en-US.md', TEMPLATE_GETTING_STARTED_MD]
   ]
 
@@ -972,6 +1002,7 @@ function initProject (name) {
   console.log(`    ${name}/`)
   console.log('    ├── docsector.config.js')
   console.log('    ├── quasar.config.js')
+  console.log('    ├── .markdownlint.json')
   console.log('    ├── package.json')
   console.log('    ├── index.html')
   console.log('    ├── postcss.config.cjs')
@@ -990,9 +1021,8 @@ function initProject (name) {
   console.log('        └── pages/')
   console.log('            ├── index.js')
   console.log('            ├── boot.js')
-  console.log('            ├── @/')
-  console.log('            │   ├── BootPage.vue')
-  console.log('            │   └── 404Page.vue')
+  console.log('            ├── Homepage.en-US.md')
+  console.log('            ├── 404Page.vue')
   console.log('            └── guide/')
   console.log('                └── getting-started.overview.en-US.md')
 

package/package.json

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

@@ -70,11 +70,19 @@ const rawMarkdown = computed(() => {
 })
 
 const markdownURL = computed(() => {
+  if (store.state.page.base === 'home') {
+    return `/Homepage.${locale.value}.md`
+  }
+
   const path = route.path.replace(/\/+$/, '')
   return `${path}.md`
 })
 
 const fullMarkdownURL = computed(() => {
+  if (store.state.page.base === 'home') {
+    return `${window.location.origin}/Homepage.${locale.value}.md`
+  }
+
   const path = route.path.replace(/\/+$/, '')
   return `${window.location.origin}${path}.md`
 })

package/src/components/DPageSection.vue

@@ -13,6 +13,7 @@ import DH6 from './DH6.vue'
 import DPageSourceCode from './DPageSourceCode.vue'
 import DMermaidDiagram from './DMermaidDiagram.vue'
 import DPageBlockquote from './DPageBlockquote.vue'
+import DQuickLinks from './DQuickLinks.vue'
 
 const props = defineProps({
   id: {
@@ -49,6 +50,71 @@ const parseAlertMarker = (rawContent = '') => {
   }
 }
 
+const QUICK_LINKS_MARKER_PREFIX = '@@DOCSECTOR_QUICK_LINKS_'
+
+const parseTagAttributes = (raw = '') => {
+  const attrs = {}
+  const pattern = /(\w+)\s*=\s*"([^"]*)"|(\w+)\s*=\s*'([^']*)'/g
+
+  let match = pattern.exec(raw)
+  while (match !== null) {
+    const key = match[1] || match[3]
+    const value = match[2] || match[4] || ''
+    attrs[key] = value
+    match = pattern.exec(raw)
+  }
+
+  return attrs
+}
+
+const extractQuickLinksBlocks = (source = '') => {
+  const map = new Map()
+  let index = 0
+
+  const blockPattern = /<d-quick-links\b([^>]*)>([\s\S]*?)<\/d-quick-links>/gi
+  const replaced = String(source).replace(blockPattern, (_, blockAttrsRaw, inner) => {
+    const blockAttrs = parseTagAttributes(blockAttrsRaw)
+    const items = []
+    const itemPattern = /<d-quick-link\b([^>]*)\/?\s*>/gi
+
+    let itemMatch = itemPattern.exec(inner)
+    while (itemMatch !== null) {
+      const attrs = parseTagAttributes(itemMatch[1])
+      const title = attrs.title || ''
+      const description = attrs.description || ''
+      const to = attrs.to || ''
+      const href = attrs.href || ''
+
+      if (title && description && (to || href)) {
+        items.push({
+          icon: attrs.icon || 'link',
+          title,
+          description,
+          to,
+          href
+        })
+      }
+
+      itemMatch = itemPattern.exec(inner)
+    }
+
+    const marker = `${QUICK_LINKS_MARKER_PREFIX}${index}@@`
+    index++
+
+    map.set(marker, {
+      title: blockAttrs.title || '',
+      items
+    })
+
+    return `\n${marker}\n`
+  })
+
+  return {
+    source: replaced,
+    quickLinksMap: map
+  }
+}
+
 const tokenized = computed(() => {
   const absolute = store.state.i18n.absolute
 
@@ -62,6 +128,8 @@ const tokenized = computed(() => {
     .replace(/&#125;/g, '}')
     .replace(/&amp;/g, '&')
 
+  const { source: sourceWithQuickLinks, quickLinksMap } = extractQuickLinksBlocks(normalizedSource)
+
   const Markdown = new MarkdownIt()
   Markdown.use(attrs, {
     leftDelimiter: ':',
@@ -75,7 +143,7 @@ const tokenized = computed(() => {
 
   const markdownEnv = {}
 
-  const parsed = Markdown.parse(normalizedSource, markdownEnv)
+  const parsed = Markdown.parse(sourceWithQuickLinks, markdownEnv)
 
   // @ map
   const tokens = []
@@ -213,6 +281,17 @@ const tokenized = computed(() => {
       // Push
       switch (element.type) {
         case 'inline':
+          if (quickLinksMap.has(element.content.trim())) {
+            const data = quickLinksMap.get(element.content.trim())
+
+            tokens.push({
+              tag: 'quick-links',
+              title: data.title,
+              items: data.items
+            })
+            break
+          }
+
           tokens.push({
             tag,
             map: element.map,
@@ -395,6 +474,12 @@ const tokenized = computed(() => {
       v-else-if="token.tag === 'mermaid'"
       :content="token.content"
     />
+
+    <d-quick-links
+      v-else-if="token.tag === 'quick-links'"
+      :title="token.title"
+      :items="token.items"
+    />
   </template>
 </section>
 </template>

package/src/components/DQuickLinks.vue

@@ -0,0 +1,98 @@
+<script setup>
+const props = defineProps({
+  items: {
+    type: Array,
+    default: () => []
+  },
+  title: {
+    type: String,
+    default: ''
+  }
+})
+
+const isExternal = (item) => {
+  const href = item?.href || ''
+  return /^https?:\/\//i.test(href)
+}
+
+const toTarget = (item) => {
+  if (item?.to) return item.to
+  return undefined
+}
+
+const hrefTarget = (item) => {
+  if (item?.href) return item.href
+  return undefined
+}
+
+const relValue = (item) => {
+  if (isExternal(item)) return 'noopener noreferrer'
+  return undefined
+}
+
+const targetValue = (item) => {
+  if (isExternal(item)) return '_blank'
+  return undefined
+}
+</script>
+
+<template>
+<div class="d-quick-links">
+  <h3 v-if="title" class="d-quick-links__title">{{ title }}</h3>
+
+  <q-list bordered separator class="d-quick-links__list rounded-borders">
+    <q-item
+      v-for="(item, index) in props.items"
+      :key="index"
+      clickable
+      :to="toTarget(item)"
+      :href="hrefTarget(item)"
+      :target="targetValue(item)"
+      :rel="relValue(item)"
+    >
+      <q-item-section avatar>
+        <q-icon :name="item.icon || 'link'" color="primary" />
+      </q-item-section>
+
+      <q-item-section>
+        <q-item-label class="d-quick-links__label">{{ item.title }}</q-item-label>
+        <q-item-label caption class="d-quick-links__caption">{{ item.description }}</q-item-label>
+      </q-item-section>
+
+      <q-item-section side>
+        <q-icon name="chevron_right" />
+      </q-item-section>
+    </q-item>
+  </q-list>
+</div>
+</template>
+
+<style lang="sass" scoped>
+.d-quick-links
+  margin: 0 auto
+
+.d-quick-links__title
+  text-align: center
+  margin: 0 0 12px
+
+.d-quick-links__list
+  border-color: rgba(255, 255, 255, 0.16)
+
+  .q-item
+    min-height: 58px
+
+.d-quick-links__label
+  font-weight: 700
+
+.d-quick-links__caption
+  font-size: 0.97rem
+  color: #4d5563
+  opacity: 1
+
+
+:global(body.body--dark) .d-quick-links__list
+  border-color: rgba(255, 255, 255, 0.16)
+
+:global(body.body--dark) .d-quick-links__caption
+  color: rgba(255, 255, 255, 0.9)
+</style>

package/src/i18n/helpers.js

@@ -144,6 +144,38 @@ export function buildMessages ({ langModules, mdModules, pages, boot, langs }) {
     return source
   }
 
+  function loadHomepage (lang) {
+    const key = `../pages/Homepage.${lang}.md`
+    const fallbackKey = '../pages/Homepage.en-US.md'
+
+    const content = mdModules[key] ?? mdModules[fallbackKey]
+    if (!content) {
+      console.warn(`[i18n] Missing homepage markdown: ${key}`)
+      return ''
+    }
+
+    const source = filter(typeof content === 'string' ? content : String(content))
+    return source
+  }
+
+  function extractHeadingFromHomepage (lang) {
+    const key = `../pages/Homepage.${lang}.md`
+    const fallbackKey = '../pages/Homepage.en-US.md'
+
+    const content = mdModules[key] ?? mdModules[fallbackKey]
+    if (!content) {
+      return ''
+    }
+
+    const raw = typeof content === 'string' ? content : String(content)
+    const match = raw.match(/^#\s+(.+)$/m)
+    if (!match) {
+      return ''
+    }
+
+    return match[1].trim()
+  }
+
   // @ Iterate langs
   for (const lang of langs) {
     // Load HJSON language file
@@ -155,6 +187,26 @@ export function buildMessages ({ langModules, mdModules, pages, boot, langs }) {
       deepMerge(i18n[lang], engineDefaults[lang])
     }
 
+    // @ Homepage markdown in root route
+    if (i18n[lang]._ === undefined) {
+      i18n[lang]._ = {}
+    }
+    if (i18n[lang]._.home === undefined) {
+      i18n[lang]._.home = {}
+    }
+
+    const homepageHeading = extractHeadingFromHomepage(lang)
+    i18n[lang]._.home._ = homepageHeading || i18n[lang]._.home._ || i18n[lang].menu?.home || 'Home'
+
+    if (i18n[lang]._.home.overview === undefined) {
+      i18n[lang]._.home.overview = {}
+    }
+
+    const homeMeta = boot?.meta?.[lang] || boot?.meta?.['en-US'] || {}
+    i18n[lang]._.home.overview._translations = homeMeta?.overview?._translations
+    i18n[lang]._.home.overview._sections = homeMeta?.overview?._sections
+    i18n[lang]._.home.overview.source = loadHomepage(lang)
+
     // @ Iterate pages
     for (const [key, page] of Object.entries(pages)) {
       const path = key.slice(1)

package/src/pages/Homepage.en-US.md

@@ -0,0 +1,17 @@
+# Docsector Reader
+
+Docsector Reader is a documentation rendering engine built with Vue 3, Quasar v2 and Vite.
+
+## Quick Links
+
+- [Getting Started](/guide/getting-started/overview/)
+- [Configuration](/guide/configuration/overview/)
+- [Pages and Routing](/guide/pages-and-routing/overview/)
+- [Components](/manual/components/d-page/overview/)
+- [Composables](/manual/composables/use-navigator/overview/)
+- [Store Modules](/manual/store/modules/overview/)
+
+## About
+
+- Repository: [docsector/docsector-reader](https://github.com/docsector/docsector-reader)
+- Focus: markdown-first docs with i18n, menu navigation and static deployment

package/src/pages/Homepage.pt-BR.md

@@ -0,0 +1,17 @@
+# Docsector Reader
+
+Docsector Reader e um motor de documentacao construído com Vue 3, Quasar v2 e Vite.
+
+## Links rapidos
+
+- [Comecando](/guide/getting-started/overview/)
+- [Configuracao](/guide/configuration/overview/)
+- [Paginas e Rotas](/guide/pages-and-routing/overview/)
+- [Componentes](/manual/components/d-page/overview/)
+- [Composables](/manual/composables/use-navigator/overview/)
+- [Modulos de Store](/manual/store/modules/overview/)
+
+## Sobre
+
+- Repositorio: [docsector/docsector-reader](https://github.com/docsector/docsector-reader)
+- Foco: docs markdown-first com i18n, menu de navegacao e deploy estatico

package/src/router/routes.js

@@ -1,4 +1,5 @@
 import pages from 'pages'
+import boot from 'pages/boot'
 
 const pagesRoutes = []
 for (const [path, page] of Object.entries(pages)) {
@@ -59,9 +60,27 @@ const routes = [
   ...pagesRoutes,
 
   {
-    path: '/',
+    path: '/home',
+    alias: '/',
     component: () => import('layouts/DefaultLayout.vue'),
     meta: {
+      icon: 'home',
+      menu: {},
+      status: 'done',
+      type: 'home',
+      subpages: {
+        showcase: false,
+        vs: false
+      },
+      data: {
+        'en-US': {
+          title: 'Home'
+        },
+        'pt-BR': {
+          title: 'Pagina inicial'
+        }
+      },
+      meta: boot.meta,
       layouts: {
         footer: false,
         submenu: false
@@ -71,7 +90,7 @@ const routes = [
     children: [
       {
         path: '',
-        component: () => import('pages/@/BootPage.vue'),
+        component: () => import('components/DSubpage.vue'),
         meta: {
           icon: 'home',
           menu: 'home'
@@ -89,7 +108,7 @@ const routes = [
     children: [
       {
         path: '',
-        component: () => import('pages/@/404Page.vue')
+        component: () => import('pages/404Page.vue')
       }
     ]
   }

package/src/store/App.js

@@ -12,10 +12,10 @@ export default {
       commit('page/resetNodes', null, { root: true })
 
       // Route
-      const firstRoutePath = routeMatched[0].path
-      const secondRoutePath = routeMatched[1].path
+      const firstRoutePath = routeMatched[0]?.path || ''
+      const secondRoutePath = routeMatched[1]?.path || ''
 
-      const base = firstRoutePath.substr(1)
+      const base = firstRoutePath === '/' ? 'home' : firstRoutePath.substr(1)
       let relative = secondRoutePath.substr(firstRoutePath.length)
 
       if (relative !== '/') {

package/src/pages/@/BootPage.vue

@@ -1,106 +0,0 @@
-<template>
-<q-page-container>
-  <q-page class="content">
-    <div class="text-center q-pa-xs q-pt-md">
-      <h1>Docsector Reader</h1>
-
-      <p class="caption">
-        {{ $t('_.home.texts[0]') }}
-        <a :href="projectUrl" target="_blank">{{ projectName }}</a>!
-      </p>
-      <hr />
-    </div>
-
-    <div class="q-pa-md" style="max-width: 700px; margin: 0 auto;">
-      <h3 class="text-center q-mb-md">Quick Links</h3>
-
-      <q-list bordered separator class="rounded-borders">
-        <q-item clickable to="/guide/getting-started/overview/">
-          <q-item-section avatar>
-            <q-icon name="flag" color="primary" />
-          </q-item-section>
-          <q-item-section>
-            <q-item-label>Getting Started</q-item-label>
-            <q-item-label caption>Installation, setup, and project structure</q-item-label>
-          </q-item-section>
-          <q-item-section side>
-            <q-icon name="chevron_right" />
-          </q-item-section>
-        </q-item>
-
-        <q-item clickable to="/guide/configuration/overview/">
-          <q-item-section avatar>
-            <q-icon name="tune" color="primary" />
-          </q-item-section>
-          <q-item-section>
-            <q-item-label>Configuration</q-item-label>
-            <q-item-label caption>docsector.config.js reference</q-item-label>
-          </q-item-section>
-          <q-item-section side>
-            <q-icon name="chevron_right" />
-          </q-item-section>
-        </q-item>
-
-        <q-item clickable to="/guide/pages-and-routing/overview/">
-          <q-item-section avatar>
-            <q-icon name="route" color="primary" />
-          </q-item-section>
-          <q-item-section>
-            <q-item-label>Pages &amp; Routing</q-item-label>
-            <q-item-label caption>Page registry and route generation</q-item-label>
-          </q-item-section>
-          <q-item-section side>
-            <q-icon name="chevron_right" />
-          </q-item-section>
-        </q-item>
-
-        <q-item clickable to="/manual/components/d-page/overview/">
-          <q-item-section avatar>
-            <q-icon name="widgets" color="secondary" />
-          </q-item-section>
-          <q-item-section>
-            <q-item-label>Components</q-item-label>
-            <q-item-label caption>DPage, DPageSection, DH1–DH6, DMenu, and more</q-item-label>
-          </q-item-section>
-          <q-item-section side>
-            <q-icon name="chevron_right" />
-          </q-item-section>
-        </q-item>
-
-        <q-item clickable to="/manual/composables/use-navigator/overview/">
-          <q-item-section avatar>
-            <q-icon name="navigation" color="accent" />
-          </q-item-section>
-          <q-item-section>
-            <q-item-label>Composables</q-item-label>
-            <q-item-label caption>useNavigator — anchor navigation and ToC</q-item-label>
-          </q-item-section>
-          <q-item-section side>
-            <q-icon name="chevron_right" />
-          </q-item-section>
-        </q-item>
-
-        <q-item clickable to="/manual/store/modules/overview/">
-          <q-item-section avatar>
-            <q-icon name="storage" color="deep-orange" />
-          </q-item-section>
-          <q-item-section>
-            <q-item-label>Vuex Store</q-item-label>
-            <q-item-label caption>App, I18n, Page, Layout, Settings modules</q-item-label>
-          </q-item-section>
-          <q-item-section side>
-            <q-icon name="chevron_right" />
-          </q-item-section>
-        </q-item>
-      </q-list>
-    </div>
-  </q-page>
-</q-page-container>
-</template>
-
-<script setup>
-import docsectorConfig from 'docsector.config.js'
-
-const projectName = docsectorConfig.branding?.name || 'My Project'
-const projectUrl = docsectorConfig.links?.github || '#'
-</script>