@docmd/core 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 docmd (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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+<div align="center">
+
+  <!-- PROJECT TITLE -->
+  <h1>
+    <img src="https://github.com/docmd-io/docmd/blob/main/src/assets/images/docmd-logo-dark.png?raw=true" alt="docmd logo" width="200" />
+    <!-- docmd -->
+  </h1>
+  
+  <!-- ONE LINE SUMMARY -->
+  <p>
+    <b>The minimalist, zero-config documentation generator.</b>
+  </p>
+  
+  <!-- BADGES -->
+  <p>
+    <a href="https://www.npmjs.com/package/@docmd/core"><img src="https://img.shields.io/npm/v/@docmd/core.svg?style=flat-square&color=d25353" alt="npm version"></a>
+    <a href="https://www.npmjs.com/package/@docmd/core?activeTab=versions"><img src="https://img.shields.io/npm/dt/@docmd/core.svg?style=flat-square&color=38bd24" alt="downloads"></a>
+    <a href="https://github.com/docmd-io/docmd/stargazers"><img src="https://img.shields.io/github/stars/docmd-io/docmd?style=flat-square&logo=github" alt="stars"></a>
+    <a href="https://github.com/docmd-io/docmd/blob/main/LICENSE"><img src="https://img.shields.io/github/license/docmd-io/docmd.svg?style=flat-square&color=blue" alt="license"></a>
+  </p>
+
+  <!-- MENU -->
+  <p>
+    <h4>
+      <a href="https://docmd.io">View Demo</a> • 
+      <a href="https://docs.docmd.io/getting-started/installation/">Documentation</a> • 
+      <a href="https://live.docmd.io">Live Editor</a> •
+      <a href="https://github.com/docmd-io/docmd/issues">Report Bug</a>
+    </h4>
+  </p>
+
+  <!-- PREVIEW -->
+  <p>
+    <img width="800" alt="docmd preview" src="https://github.com/user-attachments/assets/1a74d6f7-10f9-41fa-be8a-faeee278dbb9" />
+    <br/>
+    <sup><i>docmd noStyle page preview in light mode</i></sup>
+  </p>
+
+</div>
+
+## Features
+
+- **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**.
+- **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`).
+
+## Installation
+
+```bash
+npm install -g @docmd/core
+```
+
+## Usage
+
+### CLI
+
+The Command Line Interface is the primary way to interact with `docmd`.
+
+```bash
+docmd init      # Initialize a new project with config and assets
+docmd dev       # Start a local development server with hot-reload
+docmd build     # Generate a production-ready static site in ./site
+docmd live      # Launch the browser-based Live Editor locally
+```
+
+### API
+
+`docmd` exports its core engine, allowing you to build documentation programmatically within your own Node.js scripts or build tools.
+
+```javascript
+const { build, buildLive } = require('@docmd/core');
+
+// Trigger a standard documentation build
+await build('./docmd.config.js', { 
+  isDev: false, 
+  preserve: true 
+});
+
+// Trigger a Live Editor bundle build
+await buildLive(); 
+```
+
+### Live Editor
+
+`docmd` features a modular architecture that allows the core engine to run client-side. 
+
+Running `docmd live` builds a standalone web application where you can write Markdown and see the preview instantly without any server-side processing. You can embed the generated `docmd-live.js` bundle to add Markdown capabilities to your own applications.
+
+## Project Structure
+
+`docmd` keeps it simple. Your content lives in `docs/`, your config in `docmd.config.js`.
+
+```bash
+my-docs/
+├── docs/                  # Your Markdown files
+│   ├── index.md           # Homepage
+│   └── guide.md           # Content page
+├── assets/                # Images and custom CSS
+├── docmd.config.js        # Configuration
+└── package.json
+```
+
+## Configuration
+
+Customize your site in seconds via `docmd.config.js`:
+
+```javascript
+module.exports = {
+  siteTitle: 'My Project',
+  siteUrl: 'https://mysite.com',
+  srcDir: 'docs',
+  outputDir: 'site',
+  
+  // Theme Settings
+  theme: {
+    name: 'sky',           // 'default', 'sky', 'ruby', 'retro'
+    defaultMode: 'system', // 'light', 'dark', or 'system'
+    enableModeToggle: true
+  },
+  
+  // Sidebar Navigation
+  navigation: [
+    { title: 'Home', path: '/', icon: 'home' },
+    { 
+      title: 'Guide', 
+      icon: 'book',
+      children: [
+        { title: 'Installation', path: '/guide/install' }
+      ]
+    }
+  ],
+
+  // Plugins
+  plugins: {
+    seo: { /* ... */ },
+    sitemap: { /* ... */ }
+  }
+}
+```
+
+## Comparison
+
+| 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 |
+
+## Community & Support
+
+- **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
+
+Distributed under the MIT License. See `LICENSE` for more information.
+
+> **{ github.com/mgks }**
+> 
+> ![Website Badge](https://img.shields.io/badge/Visit-mgks.dev-blue?style=flat&link=https%3A%2F%2Fmgks.dev) ![Sponsor Badge](https://img.shields.io/badge/%20%20Become%20a%20Sponsor%20%20-red?style=flat&logo=github&link=https%3A%2F%2Fgithub.com%2Fsponsors%2Fmgks)

package/bin/docmd.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const { version } = require('../package.json');
+const { initProject } = require('../src/commands/init');
+const { buildSite } = require('../src/commands/build');
+const { startDevServer } = require('../src/commands/dev');
+const { buildLive } = require('../src/commands/live');
+const { printBanner } = require('../src/utils/logger');
+
+program
+  .name('docmd')
+  .description('The minimalist, zero-config documentation generator')
+  .version(version);
+
+program
+  .command('init')
+  .action(() => {
+    printBanner();
+    initProject();
+  });
+
+program
+  .command('build')
+  .option('-c, --config <path>', 'Path to config', 'docmd.config.js')
+  .option('--offline', 'Optimize for file:// viewing')
+  .action((opts) => {
+    buildSite(opts.config, { isDev: false, offline: opts.offline });
+  });
+
+program
+  .command('dev')
+  .option('-c, --config <path>', 'Path to config', 'docmd.config.js')
+  .option('-p, --port <number>', 'Port to run server')
+  .action((opts) => {
+    printBanner();
+    startDevServer(opts.config, opts);
+  });
+
+program
+  .command('live')
+  .action(async () => {
+    try {
+      await buildLive();
+      // ... (Add the spawn 'serve' logic here from the backup if desired)
+    } catch (e) {
+      console.error(e);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@docmd/core",
+  "version": "0.4.0",
+  "description": "The minimalist, zero-config documentation generator.",
+  "bin": {
+    "docmd": "./bin/docmd.js"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "chokidar": "^3.5.3",
+    "commander": "^11.0.0",
+    "ws": "^8.13.0",
+    "@docmd/themes": "0.4.0",
+    "@docmd/ui": "0.4.0",
+    "@docmd/parser": "0.4.0",
+    "@docmd/live": "0.4.0",
+    "@docmd/plugin-seo": "0.4.0",
+    "@docmd/plugin-sitemap": "0.4.0",
+    "@docmd/plugin-search": "0.4.0",
+    "@docmd/plugin-analytics": "0.4.0"
+  },
+  "license": "MIT"
+}

package/src/commands/build.js

@@ -0,0 +1,262 @@
+const path = require('path');
+const fs = require('../utils/fs-utils');
+const { loadConfig } = require('../utils/config-loader');
+const { loadPlugins } = require('../utils/plugin-loader');
+const parser = require('@docmd/parser');
+const ui = require('@docmd/ui');
+const themes = require('@docmd/themes');
+const { findPageNeighbors } = require('@docmd/parser/src/utils/navigation-helper');
+
+async function findMarkdownFilesRecursive(dir) {
+  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);
+    }
+  }
+  return files;
+}
+
+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}>`;
+  if (type === 'js') return `<script src="${pathOrUrl}" ${attrs}></script>`;
+  return '';
+}
+
+async function buildSite(configPath, options = { isDev: false, offline: false }) {
+  const CWD = process.cwd();
+  const config = await loadConfig(configPath);
+  const hooks = loadPlugins(config);
+  const buildHash = Date.now().toString(36);
+
+  const srcDir = path.resolve(CWD, config.srcDir);
+  const outputDir = path.resolve(CWD, config.outputDir);
+  
+  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
+  const uiAssets = ui.getAssetsDir();
+  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'));
+  }
+
+  // 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 ---
+  const assetTags = { head: [], body: [] };
+
+  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))) {
+        assetTags.head.push(rel => generateTag(`${rel}assets/css/${themeFileName}?v=${buildHash}`, 'css'));
+    } else {
+        if (!options.isDev) console.warn(`⚠️  Theme not found: ${themeFileName}`);
+    }
+  }
+
+  // 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
+  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
+  if (hooks.assets) {
+    for (const getAssetsFn of hooks.assets) {
+      const assets = getAssetsFn();
+      if (Array.isArray(assets)) {
+        for (const asset of assets) {
+          let tagGen;
+          if (asset.src && asset.dest) {
+            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);
+            }
+            tagGen = (rel) => generateTag(`${rel}${asset.dest}?v=${buildHash}`, asset.type, asset.attributes);
+          } else if (asset.url) {
+            tagGen = () => generateTag(asset.url, asset.type, asset.attributes);
+          }
+          if (tagGen) assetTags[asset.location === 'head' ? 'head' : 'body'].push(tagGen);
+        }
+      }
+    }
+  }
+
+  // --- 3. 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 pages = [];
+  
+  for (const filePath of mdFiles) {
+    const rawContent = await fs.readFile(filePath, 'utf8');
+    const processed = parser.processContent(rawContent, mdProcessor, config);
+    if (!processed) continue;
+    
+    const relativePath = path.relative(srcDir, filePath);
+    const isIndex = path.basename(relativePath).startsWith('index.');
+    const htmlOutputPath = isIndex ? path.join(path.dirname(relativePath), 'index.html') : relativePath.replace(/\.md$/, '/index.html');
+    pages.push({ ...processed, sourcePath: filePath, outputPath: htmlOutputPath });
+  }
+
+  // --- 4. 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)
+    // "content/nested/index.html" -> dir "content/nested" -> relative "../.."
+    const fileDir = path.dirname(page.outputPath); 
+    let relativePathToRoot = path.relative(fileDir, '.');
+    
+    if (relativePathToRoot === '') relativePathToRoot = './';
+    else relativePathToRoot += '/';
+    relativePathToRoot = relativePathToRoot.replace(/\\/g, '/'); // Windows fix
+
+    // 3. Normalize Nav Path for Matching
+    // We use the "clean" URL path for checking active state
+    let navPath = '/' + page.outputPath.replace(/\\/g, '/').replace(/\/index\.html$/, '').replace(/^index\.html$/, '');
+    if(navPath === '/.') navPath = '/';
+
+    // 4. Navigation & Neighbors
+    const { prevPage, nextPage } = findPageNeighbors(config.navigation, navPath);
+
+    // Fix Neighbor Links (Prepend relative root)
+    if (prevPage && !prevPage.path.startsWith('http')) {
+        let p = prevPage.path.replace(/^\//, ''); // Strip leading slash
+        if(options.offline && !p.endsWith('.html')) p = p.replace(/\/$/, '') + '/index.html';
+        prevPage.url = relativePathToRoot + p;
+    }
+    if (nextPage && !nextPage.path.startsWith('http')) {
+        let p = nextPage.path.replace(/^\//, '');
+        if(options.offline && !p.endsWith('.html')) p = p.replace(/\/$/, '') + '/index.html';
+        nextPage.url = relativePathToRoot + p;
+    }
+
+    // 5. Asset Injection (Head/Body)
+    const assetHeadHtml = assetTags.head.map(gen => gen(relativePathToRoot)).join('\n');
+    const assetBodyHtml = assetTags.body.map(gen => gen(relativePathToRoot)).join('\n');
+    
+    const pageContext = { frontmatter: page.frontmatter, outputPath: page.outputPath };
+    
+    const fullHeadHtml = [
+      hooks.injectHead.map(fn => fn(config, pageContext, relativePathToRoot)).join('\n'),
+      assetHeadHtml
+    ].join('\n');
+
+    const fullBodyHtml = [
+      assetBodyHtml,
+      hooks.injectBody.map(fn => fn(config, pageContext)).join('\n')
+    ].join('\n');
+
+    // 6. Helpers
+    let faviconLinkHtml = '';
+    if (config.favicon) {
+        const cleanFavicon = config.favicon.startsWith('/') ? config.favicon.substring(1) : config.favicon;
+        const finalFavicon = `${relativePathToRoot}${cleanFavicon}?v=${buildHash}`;
+        faviconLinkHtml = `<link rel="icon" href="${finalFavicon}" type="image/x-icon" sizes="any">\n<link rel="shortcut icon" href="${finalFavicon}" type="image/x-icon">`;
+    }
+
+    const isActivePage = page.htmlContent && page.htmlContent.trim().length > 0;
+    
+    let editUrl = null, editLinkText = 'Edit this page';
+    if (config.editLink && config.editLink.enabled && config.editLink.baseUrl) {
+         const cleanBase = config.editLink.baseUrl.replace(/\/$/, '');
+         const cleanPath = page.outputPath.replace(/\/index\.html$/, '.md');
+         editUrl = `${cleanBase}/${cleanPath}`;
+         if (page.outputPath.endsWith('index.html') && page.outputPath !== 'index.html') editUrl = editUrl.replace('.md', '/index.md');
+         if (page.outputPath === 'index.html') editUrl = `${cleanBase}/index.md`;
+         editLinkText = config.editLink.text || editLinkText;
+    }
+
+    // 7. Render
+    const templateName = page.frontmatter.noStyle ? 'no-style' : 'layout';
+    const templatePath = ui.getTemplatePath(templateName);
+    const templateString = await fs.readFile(templatePath, 'utf8');
+    const navTemplateString = await fs.readFile(ui.getTemplatePath('navigation'), 'utf8');
+    
+    const navigationHtml = parser.renderTemplate(navTemplateString, {
+      config,
+      navItems: config.navigation,
+      currentPagePath: navPath,
+      relativePathToRoot,
+      isOfflineMode: options.offline
+    }, { filename: ui.getTemplatePath('navigation') });
+
+    const fullHtml = parser.renderTemplate(templateString, {
+      content: page.htmlContent,
+      frontmatter: page.frontmatter,
+      headings: page.headings,
+      config,
+      buildHash,
+      siteTitle: config.siteTitle,
+      pageTitle: page.frontmatter.title,
+      description: page.frontmatter.description || '',
+      defaultMode: config.theme?.defaultMode || 'light',
+      relativePathToRoot,
+      isOfflineMode: options.offline,
+      navigationHtml,
+      prevPage,
+      nextPage,
+      logo: config.logo,
+      theme: config.theme,
+      sidebarConfig: config.sidebar || {},
+      footer: config.footer,
+      sponsor: config.sponsor,
+      customCssFiles: config.theme.customCss || [],
+      customJsFiles: config.customJs || [],
+      
+      pluginHeadScriptsHtml: fullHeadHtml,
+      pluginBodyScriptsHtml: fullBodyHtml,
+      
+      faviconLinkHtml,
+      themeInitScript,
+      footerHtml,
+      isActivePage,
+      editUrl,
+      editLinkText,
+      themeCssLinkHtml: '',
+      metaTagsHtml: '',
+      pluginStylesHtml: '' 
+    }, { filename: templatePath });
+
+    // 8. Write File
+    await fs.ensureDir(path.dirname(finalPath));
+    await fs.writeFile(finalPath, fullHtml);
+  }
+
+  await Promise.all(hooks.onPostBuild.map(fn => fn({ 
+    config,
+    pages,
+    outputDir,
+    log: (msg) => !options.isDev && console.log(msg)
+  })));
+  if (!options.isDev) console.log(`✅ Build complete. Generated ${pages.length} pages.`);
+}
+
+module.exports = { buildSite };