@mgks/docmd 0.3.3 → 0.3.5

package/README.md

@@ -1,68 +1,63 @@
-<p align="center">
-  <br>
+<div align="center">
   <a href="https://docmd.mgks.dev">
-    <img src="https://github.com/mgks/docmd/blob/main/src/assets/images/docmd-logo-light.png?raw=true" alt="docmd logo" width="200" />
+    <img src="https://github.com/mgks/docmd/blob/main/src/assets/images/docmd-logo-light.png?raw=true" alt="docmd logo" width="150" />
   </a>
-</p>
-
-<p align="center">
-  <b>The minimalist, zero-config documentation generator for Node.js developers.</b>
-  <br>
-  Turn Markdown into beautiful, blazing-fast websites in seconds.
-  <br>
-</p>
+  <p>
+    <strong>The minimalist, zero-config documentation generator.</strong>
+  </p>
+</div>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@mgks/docmd"><img src="https://img.shields.io/npm/v/@mgks/docmd.svg?style=flat-square&color=007acc" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/@mgks/docmd"><img src="https://img.shields.io/npm/dt/@mgks/docmd.svg?style=flat-square&color=success" alt="npm downloads"></a>
-  <a href="https://github.com/mgks/docmd/blob/main/LICENSE"><img src="https://img.shields.io/github/license/mgks/docmd.svg?style=flat-square&color=blue" alt="license"></a>
+  <a href="https://www.npmjs.com/package/@mgks/docmd"><img src="https://img.shields.io/npm/v/@mgks/docmd.svg?style=flat-square&color=fc3b53" alt="npm version"></a>
+<a href="https://github.com/mgks/docmd/commits"><img src="https://img.shields.io/github/commit-activity/m/mgks/docmd?style=flat-square&color=38bd24" alt="commits"></a>
+  <a href="https://www.npmjs.com/package/@mgks/docmd"><img src="https://img.shields.io/npm/dt/@mgks/docmd.svg?style=flat-square&color=38bd24" alt="downloads"></a>
   <a href="https://github.com/mgks/docmd/stargazers"><img src="https://img.shields.io/github/stars/mgks/docmd?style=flat-square&logo=github" alt="stars"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/mgks/docmd.svg?style=flat-square&color=blue" alt="license"></a>
 </p>
 
 <p align="center">
   <a href="https://docmd.mgks.dev"><b>View Live Demo</b></a> • 
-  <a href="https://docmd.mgks.dev/getting-started/installation/"><b>Documentation</b></a> • 
+  <a href="https://docmd.mgks.dev/getting-started/installation/"><b>Read Documentation</b></a> • 
+  <a href="https://docmd.mgks.dev/live/"><b>Live Editor</b></a> •
   <a href="https://github.com/mgks/docmd/issues"><b>Report Bug</b></a>
 </p>
 
-<br>
-
 <p align="center">
-  <img width="2856" height="1558" alt="519536477-8d948e18-8e2d-420d-8902-96e1aafab1ba-modified" src="https://docmd.mgks.dev/assets/images/preview-dark-welcome.png" />
+  <img width="800" alt="docmd preview" src="https://docmd.mgks.dev/assets/images/preview-dark-welcome.png" style="border-radius: 10px" />
+  <br/>
   <sup><i>docmd noStyle page preview in dark mode</i></sup>
 </p>
 
-## 🚀 Why docmd?
-
-Most documentation tools today are too heavy (React hydration, massive bundles) or require ecosystems you don't use (Python/Ruby).
-
-**docmd** fills the gap. It is a native Node.js tool that generates **pure, static HTML**.
+## Features
 
-*   ⚡ **Blazing Fast:** No hydration delay. Instant page loads.
-*   🔍 **Offline Search:** Powerful full-text search included automatically.
-*   🛠 **Zero Config:** Works out of the box with sensible defaults.
-*   🎨 **Theming:** Built-in light/dark modes and multiple themes (`sky`, `ruby`, `retro`).
-*   📦 **Node.js Native:** No Python, no Gemfiles. Just `npm install`.
-*   🧩 **Rich Content:** Built-in support for Callouts, Cards, Tabs, Steps, and Changelogs.
+- **Zero Config**: Works out of the box with sensible defaults. Just `init` and go.
+- **Blazing Fast**: Generates **pure, static HTML**. No React hydration lag, no heavy bundles.
+- **Smart Search**: Built-in, **offline-capable** full-text search with fuzzy matching. No API keys required.
+- **Isomorphic Core**: Runs anywhere—Node.js CLI, CI/CD pipelines, or **directly in the browser** via WASM.
+- **Rich Content**: Built-in support for Callouts, Cards, Tabs, Steps, Changelogs, and Mermaid diagrams.
+- **Theming**: Beautiful light/dark modes and multiple pre-built themes (`sky`, `ruby`, `retro`).
 
-## 🏁 Quick Start
+## Quick Start
 
-You don't need to install anything globally to try it out.
+**Installation:**
 
 ```bash
-# 1. Initialize a new project
-npx @mgks/docmd init my-docs
+npm install -g @mgks/docmd
+```
 
-# 2. Enter directory
-cd my-docs
+**Run:**
 
-# 3. Start the dev server
-npm start
+```bash
+docmd init my-docs     # Initialize a new project
+cd my-docs             # Enter directory
+docmd dev              # Start live-reloading server
+docmd build            # Generate static site for deployment
+docmd live             # Launch live editor to preview and design pages
 ```
 
-**Dev server output:**
+**Dev Server:**
 
-```
+```js
                        
      _                 _ 
    _| |___ ___ _____ _| |
@@ -72,92 +67,89 @@ npm start
    v0.x.x
 
 
-🚀 Performing initial build for dev server...
-✅ Generated sitemap at ./site/sitemap.xml
-✅ Initial build complete.
-👀 Watching for changes in:
-    - Source: ./docs
-    - Config: ./docmd.config.js
-    - Assets: ./assets
-    - docmd Templates: ./src/templates (internal)
-    - docmd Assets: ./src/assets (internal)
-🎉 Dev server started at http://localhost:3000
-Serving content from: ./site
-Live reload is active. Browser will refresh automatically when files change.
-```
-
-## ✨ Features
+🚀 Performing initial build...
 
-| Feature | Description |
-| :--- | :--- |
-| **Markdown First** | Standard Markdown + Frontmatter. No proprietary syntax to learn. |
-| **Smart CLI** | Intelligent config validation catches typos before they break your build. |
-| **Custom Containers** | Use `::: callout`, `::: card`, `::: steps`, `::: tabs`, `::: collapsible`, `::: changelog`, and more to enrich content. |
-| **Smart Search** | Built-in, offline-capable full-text search with fuzzy matching and highlighting. No API keys required. |
-| **Diagrams** | Create flowcharts, relationship diagrams, journey, piecharts, graphs, timelines and more with Mermaid. |
-| **No-Style Pages** | Create custom landing pages (highly customizable custom HTML pages) without theme constraints. |
-| **Auto Dark Mode** | Respects system preference and saves user choice. |
-| **Plugins** | SEO, Sitemap, and Analytics support included out-of-the-box. |
+👀 Watching for changes in:
+   - Source: ./docs
+   - Config: ./config.js
+   - Assets: ./assets
 
-## 🆚 Comparison
+────────────────────────────────────────
+  SERVER RUNNING  (v0.3.5)
 
-How does `docmd` stack up against the giants?
+  Local:    http://127.0.0.1:3000
+  Network:  http://192.1.1.1:3000
 
-| Feature | docmd | Docusaurus | MkDocs (Material) | Mintlify |
-| :--- | :--- | :--- | :--- | :--- |
-| **Language** | **Node.js** | React.js | Python | Proprietary |
-| **Output** | **Static HTML** | React SPA | Static HTML | Hosted / Next.js |
-| **JS Payload** | **Tiny (< 15kb)** | Heavy | Minimal | Medium |
-| **Setup** | **~2 mins** | ~15 mins | ~10 mins | Instant (SaaS) |
-| **Cost** | **100% Free OSS** | 100% Free OSS | 100% Free OSS | Freemium |
+  Serving:  ./site
+────────────────────────────────────────
+```
 
-👉 *[Read the full comparison](https://docmd.mgks.dev/comparison/)*
+## Usage in Detail
 
-## 📦 Installation
+### Project Structure
 
-For frequent use, install globally:
+`docmd` keeps it simple. Your content lives in `docs/`, your config in `docmd.config.js`.
 
 ```bash
-npm install -g @mgks/docmd
+my-docs/
+├── docs/                  # Your Markdown files
+│   ├── index.md           # Homepage
+│   └── guide.md           # Content page
+├── assets/                # Images and custom CSS
+└── docmd.config.js        # Configuration
 ```
 
-### Commands
-
-*   `docmd init` - Create a new documentation project.
-*   `docmd dev` - Start the live-reloading local server.
-*   `docmd build` - Generate static files to `site/` for deployment.
-
-## 🎨 Themes
+### Configuration
 
-Switching themes is as easy as changing one line in your `docmd.config.js`.
+Customize your site in seconds via `docmd.config.js`:
 
 ```javascript
 module.exports = {
+  siteTitle: 'My Project',
+  srcDir: 'docs',
+  outputDir: 'site',
   theme: {
-    name: 'sky', // Options: 'default', 'sky', 'ruby', 'retro'
-    defaultMode: 'dark'
-  }
+    name: 'sky',           // 'default', 'sky', 'ruby', 'retro'
+    defaultMode: 'dark',   // 'light' or 'dark'
+    enableModeToggle: true
+  },
+  navigation: [
+    { title: 'Home', path: '/', icon: 'home' },
+    { title: 'Guide', path: '/guide', icon: 'book' }
+  ]
 }
 ```
 
-## 🤝 Contributing
+## Live Editor
 
-We welcome contributions! Please see our [Contribution Guidelines](.github/CONTRIBUTING.md) for details.
+`docmd` comes with a modular architecture that allows the core engine to run client-side.
 
-1.  Fork the repository.
-2.  Create your feature branch (`git checkout -b feature/AmazingFeature`).
-3.  Commit your changes (`git commit -m 'Add some AmazingFeature'`).
-4.  Push to the branch (`git push origin feature/AmazingFeature`).
-5.  Open a Pull Request.
+**Launch locally:**
+```bash
+docmd live
+```
+This builds and serves a local editor where you can write Markdown and see the preview instantly without any server-side processing.
+
+**Embed in your app:**
+You can also use the `dist/docmd-live.js` bundle to add Markdown compilation capabilities to your own web applications.
+
+## Comparison
 
-## ❤️ Support
+| Feature | docmd | Docusaurus | MkDocs | Mintlify |
+| :--- | :--- | :--- | :--- | :--- |
+| **Language** | **Node.js** | React.js | Python | Proprietary |
+| **Output** | **Static HTML** | React SPA | Static HTML | Hosted |
+| **JS Payload** | **Tiny (< 15kb)** | Heavy | Minimal | Medium |
+| **Search** | **Built-in (Offline)** | Algolia (Ext) | Built-in | Built-in |
+| **Setup** | **~1 min** | ~15 mins | ~10 mins | Instant |
+| **Cost** | **Free OSS** | Free OSS | Free OSS | Freemium |
 
-This project is open source and free to use. If you find it valuable, please consider:
+## Community & Support
 
-1.  ⭐️ **Starring the repo** on GitHub (it helps a lot!)
-2.  ☕ **[Sponsoring the project](https://github.com/sponsors/mgks)** to support ongoing development.
+- **Contributing**: We welcome PRs! See [CONTRIBUTING.md](.github/CONTRIBUTING.md).
+- **Support**: If you find `docmd` useful, please consider [sponsoring the project](https://github.com/sponsors/mgks) or giving it a star ⭐.
 
-## 📄 License
+## License
 
 Distributed under the MIT License. See `LICENSE` for more information.
 

package/bin/docmd.js

@@ -1,113 +1,75 @@
 #!/usr/bin/env node
 
-const { Command } = require('commander');
-const fs = require('fs-extra');
-const path = require('path');
-const { version } = require('../package.json');
-const { initProject } = require('../src/commands/init');
+const { program } = require('commander');
+// This import corresponds to module.exports = { startDevServer } in src/commands/dev.js
+const { startDevServer } = require('../src/commands/dev'); 
 const { buildSite } = require('../src/commands/build');
-const { startDevServer } = require('../src/commands/dev');
+const { initProject } = require('../src/commands/init');
+const { version } = require('../package.json');
 const { printBanner } = require('../src/core/logger');
-
-// Helper function to find the config file
-const findConfigFile = () => {
-  const newConfigPath = 'docmd.config.js';
-  const oldConfigPath = 'config.js';
-
-  if (fs.existsSync(path.resolve(process.cwd(), newConfigPath))) {
-    return newConfigPath;
-  }
-  if (fs.existsSync(path.resolve(process.cwd(), oldConfigPath))) {
-    return oldConfigPath;
-  }
-  
-  throw new Error('Configuration file not found. Please create a docmd.config.js file or run "docmd init".');
-};
-
-const program = new Command();
+const path = require('path');
+const { spawn } = require('child_process');
 
 program
   .name('docmd')
-  .description('Generate beautiful, lightweight static documentation sites directly from your Markdown files.')
-  .version(version);
+  .description('The minimalist, zero-config documentation generator')
+  .version(version, '-v, --version', 'Output the current version')
+  .helpOption('-h, --help', 'Display help for command');
 
 program
   .command('init')
-  .description('Initialize a new docmd project (creates docs/ and config file)')
-  .action(async () => {
-    try {
-      await initProject();
-      console.log('✅ docmd project initialized successfully!');
-    } catch (error) {
-      console.error('❌ Error initializing project:', error.message);
-      process.exit(1);
-    }
+  .description('Initialize a new documentation project')
+  .action(() => {
+    printBanner();
+    initProject();
   });
 
 program
-  .command('build')
-  .description('Build the static site from Markdown files and config')
-  .option('-c, --config <path>', 'Path to config file')
-  .option('-p, --preserve', 'Preserve existing asset files instead of updating them')
-  .option('--no-preserve', 'Force update all asset files, overwriting existing ones')
-  .option('--silent', 'Suppress log output')
-  .action(async (options) => {
-    try {
-      if (!options.silent) { printBanner(); }
-
-      const originalLog = console.log;
-      if (options.silent) { console.log = () => {}; }
-
-      const configPath = options.config || findConfigFile();
-      console.log(`🚀 Starting build process using ${configPath}...`);
-      await buildSite(configPath, { 
-        preserve: options.preserve
-      });
-
-      console.log = originalLog;
-      if (!options.silent) {
-        console.log('✅ Build complete! Site generated in `site/` directory.');
-      }
-
-    } catch (error) {
-      console.error('❌ Build failed:', error.message);
-      // console.error(error.stack);
-      process.exit(1);
-    }
+  .command('dev')
+  .description('Start the development server with live reload')
+  .option('-c, --config <path>', 'Path to configuration file', 'docmd.config.js')
+  .option('-p, --port <number>', 'Port to run the server on')
+  .option('--preserve', 'Preserve existing assets', false)
+  .action((options) => {
+    printBanner();
+    startDevServer(options.config, options);
   });
 
 program
-  .command('dev')
-  .description('Start a live preview development server')
-  .option('-c, --config <path>', 'Path to config file')
-  .option('--port <number>', 'Specify a port for the dev server')
-  .option('-p, --preserve', 'Preserve existing asset files instead of updating them')
-  .option('--no-preserve', 'Force update all asset files, overwriting existing ones')
-  .option('--silent', 'Suppress log output')
-  .action(async (options) => {
-    try {
-      if (!options.silent) { printBanner(); }
+  .command('build')
+  .description('Build the static documentation site')
+  .option('-c, --config <path>', 'Path to configuration file', 'docmd.config.js')
+  .option('--preserve', 'Preserve existing assets', false)
+  .action((options) => {
+    buildSite(options.config, { isDev: false, preserve: options.preserve });
+  })
+  .option('--offline', 'Generate a build optimized for file:// viewing (appends index.html)', false)
+  .action((options) => {
+    buildSite(options.config, { isDev: false, preserve: options.preserve, offline: options.offline });
+  });
 
-      if (options.silent) {
-        const originalLog = console.log;
-        console.log = (message) => {
-          if (message && message.includes('Dev server started at')) {
-            originalLog(message);
-          }
-        };
+program
+  .command('live')
+  .description('Build and serve the browser-based live editor')
+  .action(() => {
+    const scriptPath = path.resolve(__dirname, '../scripts/build-live.js');
+    const distPath = path.resolve(__dirname, '../dist');
+    
+    console.log('🚀 Starting Live Editor build...');
+    
+    // Using spawn ensures the build runs in a fresh process context
+    const build = spawn(process.execPath, [scriptPath], { stdio: 'inherit' });
+    
+    build.on('close', (code) => {
+      if (code === 0) {
+        console.log('\n🌍 Launching server...');
+        console.log('   Press Ctrl+C to stop.\n');
+        
+        // Fix for Node DeprecationWarning regarding shell: true
+        const serveCmd = `npx serve "${distPath}"`;
+        spawn(serveCmd, { stdio: 'inherit', shell: true });
       }
-      const configPath = options.config || findConfigFile();
-      await startDevServer(configPath, { preserve: options.preserve, port: options.port });
-
-    } catch (error) {
-      console.error('❌ Dev server failed:', error.message);
-      // console.error(error.stack);
-      process.exit(1);
-    }
+    });
   });
 
-program.parse(process.argv);
-
-if (!process.argv.slice(2).length) {
-  program.outputHelp();
-}
+program.parse();

package/docmd.config.js

@@ -0,0 +1,175 @@
+// Source file from the docmd project — https://github.com/mgks/docmd
+
+module.exports = {
+  // --- Core Metadata ---
+  siteTitle: 'docmd',
+  siteUrl: 'https://docmd.mgks.dev', // No trailing slash
+
+  // --- Branding ---
+  logo: {
+    light: 'assets/images/docmd-logo-light.png',
+    dark: 'assets/images/docmd-logo-dark.png',
+    alt: 'docmd Logo',
+    href: './',
+  },
+  favicon: 'assets/favicon.ico',
+
+  // --- Structure ---
+  srcDir: 'docs',       // Source markdown files directory
+  outputDir: 'site',    // Output directory for generated site
+
+  // --- Features & UX ---
+  search: true,           // Built-in offline search
+  minify: true,           // Production build optimization
+  autoTitleFromH1: true,  // Auto-generate title from first H1 if frontmatter title is missing
+  copyCode: true,         // Enable "copy to clipboard" on code blocks
+  pageNavigation: true,   // Next/Prev links
+
+  // --- Sidebar & Theme ---
+  sidebar: {
+    collapsible: true,
+    defaultCollapsed: false,
+  },
+  theme: {
+    name: 'sky',            // 'default', 'sky', 'ruby', 'retro'
+    defaultMode: 'light',   // 'light' or 'dark'
+    enableModeToggle: true, // Show theme mode toggle button 
+    positionMode: 'top',    // 'top' or 'bottom' of header
+    codeHighlight: true,    // Enable code syntax highlighting
+    customCss: [],          // Add paths relative to outputDir here
+  },
+  customJs: [
+    'assets/js/docmd-image-lightbox.js',
+  ],
+
+  // --- Plugins ---
+  plugins: {
+    seo: {
+      defaultDescription: 'The minimalist, zero-config documentation generator for Node.js developers.',
+      openGraph: {
+        defaultImage: 'assets/images/docmd-preview.png',
+      },
+      twitter: {
+        cardType: 'summary_large_image',
+      }
+    },
+    analytics: {
+      googleV4: {
+        measurementId: 'G-8QVBDQ4KM1'
+      }
+    },
+    sitemap: {
+      defaultChangefreq: 'weekly',
+      defaultPriority: 0.8
+    }
+  },
+
+  // --- Doc Source Link ---
+  editLink: {
+    enabled: true,
+    baseUrl: 'https://github.com/mgks/docmd/edit/main/docs',
+    text: 'Edit this page on GitHub'
+  },
+
+  // --- Navigation ---
+  navigation: [
+    { title: 'Welcome', path: './', icon: 'feather' },
+    { title: 'Overview', path: './overview', icon: 'home' },
+
+    {
+      title: 'Getting Started',
+      icon: 'rocket',
+      path: './getting-started/',
+      children: [
+        { title: 'Installation', path: './getting-started/installation', icon: 'download' },
+        { title: 'Basic Usage', path: './getting-started/basic-usage', icon: 'play' },
+      ],
+    },
+
+    { title: 'Configuration', path: './configuration', icon: 'settings' },
+    {
+      title: 'Content',
+      icon: 'layout-template',
+      path: './content/',
+      collapsible: true,
+      children: [
+        { title: 'Markdown Syntax', path: './content/markdown-syntax', icon: 'code-2' },
+        { title: 'Frontmatter', path: './content/frontmatter', icon: 'file-text' },
+        { title: 'Images & Lightbox', path: './content/images', icon: 'image' },
+        { title: 'Search', path: './content/search', icon: 'search' },
+        { title: 'Mermaid Diagrams', path: './content/mermaid', icon: 'network' },
+        {
+          title: 'Containers',
+          path: './content/containers/',
+          icon: 'box',
+          collapsible: true,
+          children: [
+            { title: 'Callouts', path: './content/containers/callouts', icon: 'megaphone' },
+            { title: 'Cards', path: './content/containers/cards', icon: 'panel-top' },
+            { title: 'Steps', path: './content/containers/steps', icon: 'list-ordered' },
+            { title: 'Tabs', path: './content/containers/tabs', icon: 'columns-3' },
+            { title: 'Collapsible', path: './content/containers/collapsible', icon: 'chevrons-down' },
+            { title: 'Changelogs', path: './content/containers/changelogs', icon: 'history' },
+            { title: 'Buttons', path: './content/containers/buttons', icon: 'mouse-pointer-click' },
+            { title: 'Nested Containers', path: './content/containers/nested-containers', icon: 'folder-tree' },
+          ]
+        },
+        { title: 'No-Style Pages', path: './content/no-style-pages', icon: 'layout' },
+        { title: 'Live Preview', path: './content/live-preview', icon: 'monitor-play' },
+      ],
+    },
+
+    {
+      title: 'Theming',
+      icon: 'palette',
+      path: './theming/',
+      collapsible: true,
+      children: [
+        { title: 'Available Themes', path: './theming/available-themes', icon: 'layout-grid' },
+        { title: 'Light & Dark Mode', path: './theming/light-dark-mode', icon: 'sun-moon' },
+        { title: 'Custom CSS & JS', path: './theming/custom-css-js', icon: 'file-code' },
+        { title: 'Icons', path: './theming/icons', icon: 'pencil-ruler' },
+      ],
+    },
+
+    {
+      title: 'Plugins',
+      icon: 'puzzle',
+      path: './plugins/',
+      collapsible: true,
+      children: [
+        { title: 'SEO & Meta', path: './plugins/seo', icon: 'search' },
+        { title: 'Analytics', path: './plugins/analytics', icon: 'bar-chart' },
+        { title: 'Sitemap', path: './plugins/sitemap', icon: 'map' },
+      ],
+    },
+
+    {
+      title: 'Recipes',
+      icon: 'chef-hat',
+      path: './recipes/',
+      collapsible: true,
+      children: [
+        { title: 'Landing Page', path: './recipes/landing-page', icon: 'layout-template' },
+        { title: 'Custom Fonts', path: './recipes/custom-fonts', icon: 'type' },
+        { title: 'Favicon', path: './recipes/favicon', icon: 'image-plus' },
+      ],
+    },
+
+    { title: 'CLI Commands', path: './cli-commands', icon: 'terminal' },
+    { title: 'Deployment', path: './deployment', icon: 'upload-cloud' },
+    { title: 'Comparison', path: './comparison', icon: 'scale' },
+    { title: 'Contributing', path: './contributing', icon: 'git-pull-request' },
+
+    { title: 'GitHub', path: 'https://github.com/mgks/docmd', icon: 'github', external: true },
+    { title: 'Discussions', path: 'https://github.com/mgks/docmd/discussions', icon: 'message-circle', external: true },
+  ],
+
+  // --- Footer & Sponsor ---
+  footer: '© ' + new Date().getFullYear() + ' Project docmd.',
+  sponsor: {
+    enabled: true,
+    title: 'Sponsor',
+    link: 'https://github.com/sponsors/mgks',
+  },
+};