@docsector/docsector-reader 0.1.2 → 0.2.0

package/bin/docsector.js

@@ -4,15 +4,16 @@
  * Docsector Reader CLI
  *
  * Usage:
- *   docsector dev     — Start development server with hot-reload
- *   docsector build   — Build optimized SPA for production
- *   docsector serve   — Serve the production build locally
- *   docsector help    — Show help information
+ *   docsector init [name]  — Scaffold a new documentation project
+ *   docsector dev          — Start development server with hot-reload
+ *   docsector build        — Build optimized SPA for production
+ *   docsector serve        — Serve the production build locally
+ *   docsector help         — Show help information
  */
 
 import { execSync, spawn } from 'child_process'
-import { existsSync } from 'fs'
-import { resolve, dirname } from 'path'
+import { existsSync, mkdirSync, writeFileSync } from 'fs'
+import { resolve, dirname, basename } from 'path'
 import { fileURLToPath } from 'url'
 
 const __filename = fileURLToPath(import.meta.url)
@@ -22,7 +23,7 @@ const packageRoot = resolve(__dirname, '..')
 const args = process.argv.slice(2)
 const command = args[0]
 
-const VERSION = '0.1.0'
+const VERSION = '0.2.0'
 
 const HELP = `
   Docsector Reader v${VERSION}
@@ -32,16 +33,18 @@ const HELP = `
     docsector <command> [options]
 
   Commands:
-    dev        Start development server with hot-reload (port 8181)
-    build      Build optimized SPA for production (output: dist/spa/)
-    serve      Serve the production build locally
-    version    Show version number
-    help       Show this help message
+    init [name]  Scaffold a new documentation project
+    dev          Start development server with hot-reload (port 8181)
+    build        Build optimized SPA for production (output: dist/spa/)
+    serve        Serve the production build locally
+    version      Show version number
+    help         Show this help message
 
   Options:
     --port <number>   Override dev server port (default: 8181)
 
   Examples:
+    docsector init my-docs
     docsector dev
     docsector dev --port 3000
     docsector build
@@ -51,15 +54,298 @@ const HELP = `
     https://github.com/docsector/docsector-reader
 `
 
+// =============================================================================
+// Scaffold templates
+// =============================================================================
+
+function getTemplatePackageJson (name) {
+  return JSON.stringify({
+    name,
+    version: '0.1.0',
+    private: true,
+    type: 'module',
+    description: `${name} — Documentation powered by Docsector Reader`,
+    scripts: {
+      dev: 'docsector dev',
+      build: 'docsector build',
+      serve: 'docsector serve'
+    },
+    dependencies: {
+      '@docsector/docsector-reader': '^0.2.0'
+    }
+  }, null, 2)
+}
+
+const TEMPLATE_QUASAR_CONFIG = `\
+import { configure } from 'quasar/wrappers'
+import { createQuasarConfig } from '@docsector/docsector-reader/quasar-factory'
+
+export default configure(() => {
+  return createQuasarConfig({
+    projectRoot: import.meta.dirname
+  })
+})
+`
+
+const TEMPLATE_DOCSECTOR_CONFIG = `\
+/**
+ * Docsector Reader Configuration
+ *
+ * Customize how your documentation looks and behaves.
+ * Replace the values below with your project's branding and links.
+ */
+export default {
+  // @ Branding
+  branding: {
+    logo: '/images/logo.png',
+    name: 'My Documentation',
+    version: 'v0.1.0'
+  },
+
+  // @ Links
+  links: {
+    github: 'https://github.com/your-org/your-repo',
+    discussions: null,
+    chat: null,
+    email: null,
+    changelog: null,
+    roadmap: null,
+    sponsor: null,
+    explore: null
+  },
+
+  // @ GitHub
+  github: {
+    editBaseUrl: 'https://github.com/your-org/your-repo/edit/main/src/pages'
+  },
+
+  // @ Languages
+  languages: [
+    {
+      image: '/images/flags/united-states-of-america.png',
+      label: 'English (US)',
+      value: 'en-US'
+    }
+  ],
+
+  // @ Default language
+  defaultLanguage: 'en-US'
+}
+`
+
+const TEMPLATE_CSS_STUB = `\
+// Import Docsector Reader's base styles
+@import '@docsector/docsector-reader/src/css/app.sass'
+
+// Add your custom styles below
+`
+
+const TEMPLATE_I18N_INDEX = `\
+// @ Import i18n message builder from Docsector Reader
+import { buildMessages } from '@docsector/docsector-reader/i18n'
+
+// @ 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' })
+
+// @ Import pages
+import boot from 'pages/boot'
+import pages from 'pages'
+
+export default buildMessages({ langModules, mdModules, pages, boot })
+`
+
+const TEMPLATE_I18N_HJSON = `\
+{
+  // Main navigation and UI labels for your documentation
+  nav: {
+    overview: Overview
+  }
+
+  // Page-specific translations (auto-loaded from pages/*.md)
+  pages: {}
+}
+`
+
+const TEMPLATE_PAGES_INDEX = `\
+/**
+ * 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.
+ *
+ * config.type: top-level route prefix — 'manual', 'guide', etc.
+ * config.status: 'done' | 'draft' | 'empty'
+ * config.icon: Material Design icon name
+ * config.menu: menu display options (header, subheader, separator)
+ * config.subpages: { showcase: bool, vs: bool }
+ * data: per-language titles (used for navigation and <title> tag)
+ *
+ * Set config to null for category nodes (non-navigable groupings).
+ */
+export default {
+  '/getting-started': {
+    config: {
+      icon: 'flag',
+      status: 'done',
+      type: 'guide',
+      menu: {
+        header: {
+          icon: 'school',
+          label: 'Guides'
+        }
+      },
+      subpages: {
+        showcase: false
+      }
+    },
+    data: {
+      'en-US': { title: 'Getting Started' }
+    }
+  }
+}
+`
+
+const TEMPLATE_PAGES_BOOT = `\
+export default {
+  meta: {
+    'en-US': {
+      overview: {
+        _translations: null
+      }
+    }
+  }
+}
+`
+
+const TEMPLATE_BOOT_PAGE = `\
+<template>
+  <q-page class="flex flex-center column q-pa-xl">
+    <h1 class="text-h3 text-weight-bold q-mb-md">
+      Welcome to your Documentation
+    </h1>
+    <p class="text-subtitle1 text-grey-7">
+      Edit <code>src/pages/@/BootPage.vue</code> to customize this page.
+    </p>
+    <q-btn
+      color="primary"
+      label="Getting Started"
+      to="/en-US/guide/getting-started/overview"
+      class="q-mt-lg"
+    />
+  </q-page>
+</template>
+
+<script setup>
+defineOptions({ name: 'BootPage' })
+</script>
+`
+
+const TEMPLATE_404_PAGE = `\
+<template>
+  <q-page class="flex flex-center column q-pa-xl">
+    <h1 class="text-h3 text-weight-bold q-mb-md">404</h1>
+    <p class="text-subtitle1 text-grey-7">
+      Page not found.
+    </p>
+    <q-btn
+      flat
+      color="primary"
+      label="Go Home"
+      to="/"
+    />
+  </q-page>
+</template>
+
+<script setup>
+defineOptions({ name: 'NotFoundPage' })
+</script>
+`
+
+const TEMPLATE_INDEX_HTML = `\
+<!DOCTYPE html>
+<html>
+  <head>
+    <title><%= productName %></title>
+
+    <meta charset="utf-8">
+    <meta name="description" content="<%= productDescription %>">
+    <meta name="format-detection" content="telephone=no">
+    <meta name="msapplication-tap-highlight" content="no">
+    <meta name="viewport" content="user-scalable=yes, initial-scale=1, maximum-scale=5, minimum-scale=1, width=device-width">
+
+    <link rel="icon" type="image/png" sizes="128x128" href="images/icons/favicon-128.png">
+    <link rel="icon" type="image/png" sizes="32x32" href="images/icons/favicon-32.png">
+    <link rel="icon" type="image/png" sizes="16x16" href="images/icons/favicon-16.png">
+    <link rel="icon" type="image/ico" href="favicon.ico">
+  </head>
+  <body>
+    <!-- quasar:entry-point -->
+  </body>
+</html>
+`
+
+const TEMPLATE_POSTCSS = `\
+module.exports = {
+  plugins: [
+    require('autoprefixer')
+  ]
+}
+`
+
+const TEMPLATE_GITIGNORE = `\
+node_modules
+.quasar
+dist
+npm-debug.log*
+.DS_Store
+.thumbs.db
+`
+
+const TEMPLATE_GETTING_STARTED_MD = `\
+# Getting Started
+
+Welcome to your documentation project!
+
+## Installation
+
+\\\`\\\`\\\`bash
+npm install
+\\\`\\\`\\\`
+
+## Development
+
+\\\`\\\`\\\`bash
+npm run dev
+\\\`\\\`\\\`
+
+Your documentation will be available at **http://localhost:8181**.
+
+## Next Steps
+
+- Edit pages in \\\`src/pages/\\\`
+- Add languages in \\\`src/i18n/languages/\\\`
+- Customize branding in \\\`docsector.config.js\\\`
+`
+
+// =============================================================================
+// Commands
+// =============================================================================
+
 function findQuasarBin () {
-  // Try local node_modules first (user's project)
+  // Try local @quasar/app-vite first (user's project or hoisted)
+  const localAppVite = resolve(process.cwd(), 'node_modules', '@quasar', 'app-vite', 'bin', 'quasar.js')
+  if (existsSync(localAppVite)) return localAppVite
+
+  // Try package's own node_modules (nested dependency)
+  const pkgAppVite = resolve(packageRoot, 'node_modules', '@quasar', 'app-vite', 'bin', 'quasar.js')
+  if (existsSync(pkgAppVite)) return pkgAppVite
+
+  // Fallback: try generic quasar bin in local node_modules
   const localBin = resolve(process.cwd(), 'node_modules', '.bin', 'quasar')
   if (existsSync(localBin)) return localBin
 
-  // Try package's own node_modules
-  const pkgBin = resolve(packageRoot, 'node_modules', '.bin', 'quasar')
-  if (existsSync(pkgBin)) return pkgBin
-
   // Fall back to npx
   return 'npx quasar'
 }
@@ -90,7 +376,112 @@ function run (cmd, cmdArgs = []) {
   })
 }
 
+/**
+ * Scaffold a new Docsector documentation project.
+ */
+function initProject (name) {
+  if (!name) {
+    name = 'my-docs'
+    console.log(`  No project name specified, using "${name}"`)
+  }
+
+  const projectDir = resolve(process.cwd(), name)
+
+  if (existsSync(projectDir)) {
+    console.error(`\n  Error: Directory "${name}" already exists.\n`)
+    process.exit(1)
+  }
+
+  console.log(`\n  Creating Docsector project in ${projectDir}...\n`)
+
+  // Create directory structure
+  const dirs = [
+    '',
+    'src',
+    'src/css',
+    'src/i18n',
+    'src/i18n/languages',
+    'src/pages',
+    'src/pages/@',
+    'src/pages/getting-started',
+    'src/pages/getting-started/en-US',
+    'public',
+    'public/images',
+    'public/images/icons',
+    'public/images/flags'
+  ]
+
+  for (const dir of dirs) {
+    mkdirSync(resolve(projectDir, dir), { recursive: true })
+  }
+
+  // Create files
+  const files = [
+    ['package.json', getTemplatePackageJson(name)],
+    ['quasar.config.js', TEMPLATE_QUASAR_CONFIG],
+    ['docsector.config.js', TEMPLATE_DOCSECTOR_CONFIG],
+    ['index.html', TEMPLATE_INDEX_HTML],
+    ['postcss.config.cjs', TEMPLATE_POSTCSS],
+    ['.gitignore', TEMPLATE_GITIGNORE],
+    ['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/boot.js', TEMPLATE_PAGES_BOOT],
+    ['src/pages/@/BootPage.vue', TEMPLATE_BOOT_PAGE],
+    ['src/pages/@/404Page.vue', TEMPLATE_404_PAGE],
+    ['src/pages/getting-started/en-US/overview.md', TEMPLATE_GETTING_STARTED_MD]
+  ]
+
+  for (const [filePath, content] of files) {
+    writeFileSync(resolve(projectDir, filePath), content, 'utf-8')
+  }
+
+  console.log('  Project structure:')
+  console.log(`    ${name}/`)
+  console.log('    ├── docsector.config.js')
+  console.log('    ├── quasar.config.js')
+  console.log('    ├── package.json')
+  console.log('    ├── index.html')
+  console.log('    ├── postcss.config.cjs')
+  console.log('    ├── .gitignore')
+  console.log('    ├── public/')
+  console.log('    │   └── images/')
+  console.log('    └── src/')
+  console.log('        ├── css/')
+  console.log('        │   └── app.sass')
+  console.log('        ├── i18n/')
+  console.log('        │   ├── index.js')
+  console.log('        │   └── languages/')
+  console.log('        │       └── en-US.hjson')
+  console.log('        └── pages/')
+  console.log('            ├── index.js')
+  console.log('            ├── boot.js')
+  console.log('            ├── @/')
+  console.log('            │   ├── BootPage.vue')
+  console.log('            │   └── 404Page.vue')
+  console.log('            └── getting-started/')
+  console.log('                └── en-US/')
+  console.log('                    └── overview.md')
+
+  console.log('\n  Next steps:\n')
+  console.log(`    cd ${name}`)
+  console.log('    npm install')
+  console.log('    npx docsector dev')
+  console.log('')
+  console.log('  Then open http://localhost:8181 in your browser.')
+  console.log('')
+}
+
+// =============================================================================
+// Command dispatcher
+// =============================================================================
+
 switch (command) {
+  case 'init':
+    initProject(args[1])
+    break
+
   case 'dev': {
     const portIdx = args.indexOf('--port')
     const extraArgs = []

package/package.json

@@ -1,19 +1,27 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "0.1.2",
+  "version": "0.2.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",
   "license": "MIT",
   "private": false,
+  "readmeFilename": "README.md",
   "type": "module",
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js",
-    "./config": "./docsector.config.js"
+    "./config": "./docsector.config.js",
+    "./quasar-factory": "./src/quasar.factory.js",
+    "./i18n": "./src/i18n/helpers.js",
+    "./boot/store": "./src/boot/store.js",
+    "./boot/QZoom": "./src/boot/QZoom.js",
+    "./boot/i18n": "./src/boot/i18n.js",
+    "./boot/axios": "./src/boot/axios.js",
+    "./src/css/*": "./src/css/*"
   },
   "bin": {
-    "docsector": "./bin/docsector.js"
+    "docsector": "bin/docsector.js"
   },
   "files": [
     "bin/",
@@ -63,7 +71,11 @@
     "vue": "^3.5.13",
     "vue-i18n": "^9.0.0",
     "vue-router": "^4.0.0",
-    "vuex": "^4.0.1"
+    "vuex": "^4.0.1",
+    "hjson": "^3.2.2",
+    "markdown-it": "^13.0.1",
+    "markdown-it-attrs": "^4.1.6",
+    "prismjs": "^1.27.0"
   },
   "devDependencies": {
     "@quasar/app-vite": "^2.1.0",
@@ -75,11 +87,7 @@
     "eslint-plugin-n": "^15.0.0",
     "eslint-plugin-promise": "^6.0.0",
     "eslint-plugin-vue": "^9.0.0",
-    "hjson": "^3.2.2",
-    "markdown-it": "^13.0.1",
-    "markdown-it-attrs": "^4.1.6",
-    "prettier": "^2.5.1",
-    "prismjs": "^1.27.0"
+    "prettier": "^2.5.1"
   },
   "browserslist": [
     "last 10 Chrome versions",
@@ -93,7 +101,7 @@
     "last 5 Opera versions"
   ],
   "engines": {
-    "node": "^20 || ^18",
+    "node": "^22 || ^20 || ^18",
     "npm": ">= 9"
   }
 }

package/quasar.config.js

@@ -1,117 +1,10 @@
 /* eslint-env node */
 
 import { configure } from 'quasar/wrappers'
-import { readFileSync } from 'fs'
-import { fileURLToPath } from 'url'
-import { dirname, resolve } from 'path'
-import HJSON from 'hjson'
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = dirname(__filename)
+import { createQuasarConfig } from './src/quasar.factory.js'
 
 export default configure((/* ctx */) => {
-  return {
-    boot: [
-      'store',
-      'QZoom',
-      'i18n',
-      'axios'
-    ],
-
-    css: [
-      'app.sass'
-    ],
-
-    extras: [
-      'fontawesome-v5',
-      'roboto-font',
-      'material-icons'
-    ],
-
-    build: {
-      target: {
-        browser: ['es2022', 'firefox115', 'chrome115', 'safari14'],
-        node: 'node20'
-      },
-
-      vueRouterMode: 'history',
-
-      vitePlugins: [
-        // HJSON loader plugin
-        {
-          name: 'vite-plugin-hjson',
-          transform (code, id) {
-            if (id.endsWith('.hjson')) {
-              const parsed = HJSON.parse(readFileSync(id, 'utf-8'))
-              return {
-                code: `export default ${JSON.stringify(parsed, null, 2)};`,
-                map: null
-              }
-            }
-          }
-        }
-      ],
-
-      extendViteConf (viteConf) {
-        viteConf.resolve = viteConf.resolve || {}
-        viteConf.resolve.alias = viteConf.resolve.alias || {}
-        viteConf.resolve.alias['docsector.config.js'] = resolve(__dirname, 'docsector.config.js')
-      }
-    },
-
-    devServer: {
-      port: 8181,
-      open: false
-    },
-
-    framework: {
-      config: {},
-      lang: 'en-US',
-      plugins: [
-        'LocalStorage', 'SessionStorage'
-      ]
-    },
-
-    animations: ['zoomIn', 'zoomOut'],
-
-    pwa: {
-      workboxMode: 'GenerateSW',
-      manifest: {
-        name: 'Docsector Documentation System',
-        short_name: 'Docsector Docs',
-        description: 'Streamline your documentation process with Docsector.',
-        display: 'standalone',
-        orientation: 'portrait',
-        background_color: '#ffffff',
-        theme_color: '#655529',
-        icons: [
-          {
-            src: 'icons/icon-128x128.png',
-            sizes: '128x128',
-            type: 'image/png'
-          },
-          {
-            src: 'icons/icon-192x192.png',
-            sizes: '192x192',
-            type: 'image/png'
-          },
-          {
-            src: 'icons/icon-256x256.png',
-            sizes: '256x256',
-            type: 'image/png'
-          },
-          {
-            src: 'icons/icon-384x384.png',
-            sizes: '384x384',
-            type: 'image/png'
-          },
-          {
-            src: 'icons/icon-512x512.png',
-            sizes: '512x512',
-            type: 'image/png'
-          }
-        ]
-      }
-    }
-  }
+  return createQuasarConfig({
+    projectRoot: import.meta.dirname
+  })
 })

package/src/components/DH1.vue

@@ -3,7 +3,7 @@ import { computed, onMounted, onUpdated } from 'vue'
 import { useStore } from 'vuex'
 import { useI18n } from "vue-i18n";
 
-import useNavigator from 'src/composables/useNavigator'
+import useNavigator from '../composables/useNavigator'
 
 const props = defineProps({
   id: {

package/src/components/DH2.vue

@@ -1,7 +1,7 @@
 <script setup>
 import { watch, onMounted, onUpdated } from 'vue'
 
-import useNavigator from 'src/composables/useNavigator'
+import useNavigator from '../composables/useNavigator'
 
 const props = defineProps({
   id: {

package/src/components/DH3.vue

@@ -1,7 +1,7 @@
 <script setup>
 import { watch, onMounted, onUpdated } from 'vue'
 
-import useNavigator from 'src/composables/useNavigator'
+import useNavigator from '../composables/useNavigator'
 
 const props = defineProps({
   id: {

package/src/components/DH4.vue

@@ -1,7 +1,7 @@
 <script setup>
 import { watch } from 'vue'
 
-import useNavigator from 'src/composables/useNavigator'
+import useNavigator from '../composables/useNavigator'
 
 const props = defineProps({
   id: {