@docmd/core 0.4.3 → 0.4.5

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 docmd (docmd.io)
+Copyright (c) 2025 docmd.io
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -157,6 +157,26 @@ module.exports = {
 - **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 ⭐.
 
+## The docmd Ecosystem
+
+`docmd` is a modular system. Here are the official packages:
+
+**The Engine**
+*   [**@docmd/core**](https://www.npmjs.com/package/@docmd/core) - The CLI runner and build orchestrator.
+*   [**@docmd/parser**](https://www.npmjs.com/package/@docmd/parser) - The pure Markdown-to-HTML logic.
+*   [**@docmd/live**](https://www.npmjs.com/package/@docmd/live) - The browser-based Live Editor bundle.
+
+**Interface & Design**
+*   [**@docmd/ui**](https://www.npmjs.com/package/@docmd/ui) - Base EJS templates and assets.
+*   [**@docmd/themes**](https://www.npmjs.com/package/@docmd/themes) - Official themes (Sky, Ruby, Retro).
+
+**Plugins**
+*   [**@docmd/plugin-search**](https://www.npmjs.com/package/@docmd/plugin-search) - Offline full-text search.
+*   [**@docmd/plugin-mermaid**](https://www.npmjs.com/package/@docmd/plugin-mermaid) - Diagrams and flowcharts.
+*   [**@docmd/plugin-seo**](https://www.npmjs.com/package/@docmd/plugin-seo) - Meta tags and Open Graph data.
+*   [**@docmd/plugin-sitemap**](https://www.npmjs.com/package/@docmd/plugin-sitemap) - Automatic sitemap generation.
+*   [**@docmd/plugin-analytics**](https://www.npmjs.com/package/@docmd/plugin-analytics) - Google Analytics integration.
+
 ## License
 
 Distributed under the MIT License. See `LICENSE` for more information.

package/bin/docmd.js

@@ -1,5 +1,19 @@
 #!/usr/bin/env node
 
+/**
+ * --------------------------------------------------------------------
+ * docmd : the minimalist, zero-config documentation generator.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025 docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ */
+
 const { program } = require('commander');
 const { version } = require('../package.json');
 const { initProject } = require('../src/commands/init');
@@ -39,10 +53,11 @@ program
 
 program
   .command('live')
-  .action(async () => {
+  .description('Launch the Live Editor')
+  .option('--build-only', 'Generate the dist/ folder without starting the server')
+  .action(async (opts) => {
     try {
-      await buildLive();
-
+      await buildLive({ serve: !opts.buildOnly });
     } catch (e) {
       console.error(e);
       process.exit(1);

package/package.json

@@ -1,20 +1,21 @@
 {
   "name": "@docmd/core",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "The minimalist, zero-config documentation generator.",
   "bin": {
     "docmd": "bin/docmd.js"
   },
   "dependencies": {
-    "@docmd/parser": "^0.4.3",
-    "@docmd/ui": "^0.4.3",
-    "@docmd/themes": "^0.4.3",
-    "@docmd/live": "^0.4.3",
-    "@docmd/plugin-search": "^0.4.3",
-    "@docmd/plugin-seo": "^0.4.3",
-    "@docmd/plugin-sitemap": "^0.4.3",
-    "@docmd/plugin-analytics": "^0.4.3",
-    "@docmd/plugin-mermaid": "^0.4.3",
+    "@docmd/parser": "^0.4.5",
+    "@docmd/ui": "^0.4.5",
+    "@docmd/themes": "^0.4.5",
+    "@docmd/live": "^0.4.5",
+    "@docmd/plugin-search": "^0.4.5",
+    "@docmd/plugin-seo": "^0.4.5",
+    "@docmd/plugin-sitemap": "^0.4.5",
+    "@docmd/plugin-analytics": "^0.4.5",
+    "@docmd/plugin-mermaid": "^0.4.5",
+    "esbuild": "^0.25.0",
     "chalk": "^4.1.2",
     "chokidar": "^3.5.3",
     "commander": "^11.0.0",

package/src/commands/build.js

@@ -1,3 +1,17 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the minimalist, zero-config documentation generator.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025 docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ */
+
 const path = require('path');
 const fs = require('../utils/fs-utils');
 const { loadConfig } = require('../utils/config-loader');
@@ -6,22 +20,68 @@ const parser = require('@docmd/parser');
 const ui = require('@docmd/ui');
 const themes = require('@docmd/themes');
 const { findPageNeighbors } = require('@docmd/parser/src/utils/navigation-helper');
+const esbuild = require('esbuild');
+
+const COPYRIGHT_BANNER = `/*!
+ * --------------------------------------------------------------------
+ * docmd : the minimalist, zero-config documentation generator.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025-present docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ */`;
 
-async function findMarkdownFilesRecursive(dir) {
+// Recursively find files with specific extensions
+async function findFilesRecursive(dir, extensions) {
   let files = [];
   if (!await fs.exists(dir)) return [];
   const items = await fs.readdir(dir, { withFileTypes: true });
   for (const item of items) {
     const fullPath = path.join(dir, item.name);
     if (item.isDirectory()) {
-      files = files.concat(await findMarkdownFilesRecursive(fullPath));
-    } else if (item.isFile() && (item.name.endsWith('.md') || item.name.endsWith('.markdown'))) {
-      files.push(fullPath);
+      files = files.concat(await findFilesRecursive(fullPath, extensions));
+    } else if (item.isFile()) {
+      // If extensions is null, get all files. Otherwise check list.
+      if (!extensions || extensions.includes(path.extname(item.name))) {
+        files.push(fullPath);
+      }
     }
   }
   return files;
 }
 
+// Minify CSS and JS assets in the output directory
+async function minifyAssets(outputDir) {
+  const assets = await findFilesRecursive(path.join(outputDir, 'assets'), ['.css', '.js']);
+
+  for (const file of assets) {
+    if (file.endsWith('.min.js') || file.endsWith('.min.css')) continue;
+
+    try {
+      const ext = path.extname(file);
+      const content = await fs.readFile(file, 'utf8');
+      
+      const result = await esbuild.transform(content, {
+        loader: ext.slice(1),
+        minify: true,
+        legalComments: 'none' 
+      });
+
+      const finalContent = COPYRIGHT_BANNER + '\n' + result.code;
+
+      await fs.writeFile(file, finalContent);
+    } catch (e) {
+      console.warn(`⚠️  Minification failed for ${path.basename(file)}: ${e.message}`);
+    }
+  }
+}
+
+// Generate HTML tag for asset
 function generateTag(pathOrUrl, type, attributes = {}) {
   const attrs = Object.entries(attributes).map(([k,v]) => v === true ? k : `${k}="${v}"`).join(' ');
   if (type === 'css') return `<link rel="stylesheet" href="${pathOrUrl}" ${attrs}>`;
@@ -29,6 +89,7 @@ function generateTag(pathOrUrl, type, attributes = {}) {
   return '';
 }
 
+// Main Build Function
 async function buildSite(configPath, options = { isDev: false, offline: false }) {
   const CWD = process.cwd();
   const config = await loadConfig(configPath);
@@ -41,28 +102,20 @@ async function buildSite(configPath, options = { isDev: false, offline: false })
   if (!await fs.exists(srcDir)) throw new Error(`Source directory not found: ${srcDir}`);
   await fs.ensureDir(outputDir);
 
-  // --- 1. ASSET COPYING (Simplified) ---
-  
-  // A. Copy ALL UI Assets (Deep copy)
-  // This handles css, js, images, AND favicon.ico in root of assets
+// --- 1. ASSET COPYING (Core & Themes) ---
   const uiAssets = ui.getAssetsDir();
-  if (await fs.exists(uiAssets)) {
-    await fs.copy(uiAssets, path.join(outputDir, 'assets'));
-  }
+  if (await fs.exists(uiAssets)) await fs.copy(uiAssets, path.join(outputDir, 'assets'));
 
-  // B. Copy Themes
   const themesDir = themes.getThemesDir();
-  if (await fs.exists(themesDir)) {
-    await fs.copy(themesDir, path.join(outputDir, 'assets/css'));
-  }
+  if (await fs.exists(themesDir)) await fs.copy(themesDir, path.join(outputDir, 'assets/css'));
 
-  // C. Copy User Assets (Override)
   const userAssets = path.resolve(CWD, 'assets');
   if (await fs.exists(userAssets)) await fs.copy(userAssets, path.join(outputDir, 'assets'));
 
-  // --- 2. GENERATE TAGS ---
+  // --- 2. GENERATE TAGS & COPY PLUGIN ASSETS ---
   const assetTags = { head: [], body: [] };
 
+  // Theme CSS Tag
   if (config.theme && config.theme.name && config.theme.name !== 'default') {
     const themeFileName = `docmd-theme-${config.theme.name}.css`;
     if (await fs.exists(path.join(themes.getThemesDir(), themeFileName))) {
@@ -72,15 +125,12 @@ async function buildSite(configPath, options = { isDev: false, offline: false })
     }
   }
 
-  // Core JS (Keep this, or move to EJS if you want full control, but keeping here is fine)
-  assetTags.body.push(rel => generateTag(`${rel}assets/js/docmd-main.js?v=${buildHash}`, 'js'));
-  
-  // Lightbox
+  // Lightbox Tag
   if(await fs.exists(path.join(uiAssets, 'js/docmd-image-lightbox.js'))) {
       assetTags.body.push(rel => generateTag(`${rel}assets/js/docmd-image-lightbox.js?v=${buildHash}`, 'js'));
   }
 
-  // Plugin Assets
+  // Plugin Assets Loop
   if (hooks.assets) {
     for (const getAssetsFn of hooks.assets) {
       const assets = getAssetsFn();
@@ -88,11 +138,13 @@ async function buildSite(configPath, options = { isDev: false, offline: false })
         for (const asset of assets) {
           let tagGen;
           if (asset.src && asset.dest) {
+            // Copy the file to output
             const destPath = path.join(outputDir, asset.dest);
             if (await fs.exists(asset.src)) {
               await fs.ensureDir(path.dirname(destPath));
               await fs.copy(asset.src, destPath);
             }
+            // Generate the HTML tag
             tagGen = (rel) => generateTag(`${rel}${asset.dest}?v=${buildHash}`, asset.type, asset.attributes);
           } else if (asset.url) {
             tagGen = () => generateTag(asset.url, asset.type, asset.attributes);
@@ -103,14 +155,19 @@ async function buildSite(configPath, options = { isDev: false, offline: false })
     }
   }
 
-  // --- 3. PROCESSING ---
+  // --- 3. ASSET MINIFICATION ---
+  if (config.minify !== false && !options.isDev) {
+      await minifyAssets(outputDir);
+  }
+
+  // --- 4. PROCESSING ---
   const mdProcessor = parser.createMarkdownProcessor(config, (md) => hooks.markdownSetup.forEach(hook => hook(md)));
   const themeInitPath = path.join(ui.getTemplatesDir(), 'partials', 'theme-init.js');
   let themeInitScript = '';
   if (await fs.exists(themeInitPath)) themeInitScript = `<script>${await fs.readFile(themeInitPath, 'utf8')}</script>`;
   let footerHtml = config.footer ? mdProcessor.renderInline(config.footer) : '';
 
-  const mdFiles = await findMarkdownFilesRecursive(srcDir);
+  const mdFiles = await findFilesRecursive(srcDir, ['.md', '.markdown']);
   const pages = [];
   
   for (const filePath of mdFiles) {
@@ -124,12 +181,12 @@ async function buildSite(configPath, options = { isDev: false, offline: false })
     pages.push({ ...processed, sourcePath: filePath, outputPath: htmlOutputPath });
   }
 
-  // --- 4. RENDER LOOP ---
+  // --- 5. RENDER LOOP ---
   for (const page of pages) {
     // 1. Determine Output Location
     const finalPath = path.join(outputDir, page.outputPath);
     
-    // 2. Calculate Relative Path to Root (CRITICAL FIX)
+    // 2. Calculate Relative Path to Root
     // "content/nested/index.html" -> dir "content/nested" -> relative "../.."
     const fileDir = path.dirname(page.outputPath); 
     let relativePathToRoot = path.relative(fileDir, '.');

package/src/commands/dev.js

@@ -1,4 +1,16 @@
-// Source file from the docmd project — https://github.com/docmd-io/docmd
+/**
+ * --------------------------------------------------------------------
+ * docmd : the minimalist, zero-config documentation generator.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025 docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ */
 
 const http = require('http');
 const WebSocket = require('ws');

package/src/commands/init.js

@@ -1,4 +1,16 @@
-// Source file from the docmd project — https://github.com/docmd-io/docmd
+/**
+ * --------------------------------------------------------------------
+ * docmd : the minimalist, zero-config documentation generator.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025 docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ */
 
 const fs = require('../utils/fs-utils');
 const path = require('path');

package/src/commands/live.js

@@ -1,3 +1,17 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the minimalist, zero-config documentation generator.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025 docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ */
+
 async function buildLive(options = {}) {
   // Delegate to the standalone package
   const livePkg = require('@docmd/live');

package/src/utils/config-loader.js

@@ -1,3 +1,17 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the minimalist, zero-config documentation generator.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025 docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ */
+
 const path = require('path');
 const fs = require('fs');
 const { validateConfig } = require('@docmd/parser'); 

package/src/utils/fs-utils.js

@@ -1,4 +1,16 @@
-// Source file from the docmd project — https://github.com/docmd-io/docmd
+/**
+ * --------------------------------------------------------------------
+ * docmd : the minimalist, zero-config documentation generator.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025 docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ */
 
 const fs = require('node:fs/promises');
 const path = require('node:path');

package/src/utils/logger.js

@@ -1,4 +1,16 @@
-// Source file from the docmd project — https://github.com/docmd-io/docmd
+/**
+ * --------------------------------------------------------------------
+ * docmd : the minimalist, zero-config documentation generator.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025 docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ */
 
 const chalk = require('chalk');
 

package/src/utils/plugin-loader.js

@@ -1,3 +1,17 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the minimalist, zero-config documentation generator.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025 docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ */
+
 const chalk = require('chalk');
 
 const hooks = {

package/src/utils/plugin-runner.js

@@ -1,3 +1,17 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the minimalist, zero-config documentation generator.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025 docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ */
+
 const { onPostBuild: searchPostBuild, getClientAssets: getSearchAssets } = require('@docmd/plugin-search');
 const { onPostBuild: sitemapPostBuild } = require('@docmd/plugin-sitemap');
 // We will implement SEO/Analytics later, but they are typically "hooks" inside the HTML generation