@mgks/docmd 0.2.5 → 0.2.6

package/README.md

@@ -5,8 +5,8 @@
 </p>
 
 <p align="center">
-  <b>Generate beautiful, lightweight static documentation sites from Markdown files.</b><br>
-  Zero clutter, just content.
+  <b>Generate beautiful, lightweight static documentation sites from Markdown files.</b>
+  <br>Zero clutter, just content.
 </p>
 
 <p align="center">
@@ -15,71 +15,94 @@
   <a href="https://github.com/mgks/docmd/blob/main/LICENSE"><img src="https://img.shields.io/github/license/mgks/docmd.svg" alt="license"></a>
 </p>
 
-Docmd (`docmd`) is a Node.js command-line tool dedicated to generating beautiful, lightweight static documentation sites from standard Markdown files. It champions the philosophy of "zero clutter, just content," prioritizing ease of use for documentation authors and a clean, performant experience for readers.
+Docmd is a Node.js command-line tool for generating fast, beautiful, and lightweight static documentation sites from standard Markdown files. It champions the philosophy of "zero clutter, just content," prioritizing a simple authoring experience and a clean, performant result for readers.
 
-#### 🟢 [Live Preview](https://docmd.mgks.dev): Documentation site powered entirely by *Docmd*, serving as both the official docs and a live demo.
+**:rocket: [Live Preview](https://docmd.mgks.dev): Official documentation site powered by `docmd`.**
 
-## Features
+## Key Features
 
-- 📝 **Markdown First** - Standard Markdown with YAML frontmatter
-- 🎨 **Beautiful Themes** - Multiple themes and light/dark modes with syntax highlighting
-- 🚀 **Fast & Lightweight** - Static site generation with minimal JS
-- 🧩 **Custom Components** - Callouts, cards, steps, and more
-- 🔌 **Built-in Plugins** - SEO, Analytics, and Sitemap support
-- 🎭 **No-Style Pages** - Create custom standalone pages with complete HTML control
-- 🖌️ **Custom Styling** - Add custom CSS/JS and HTML directly in frontmatter
-- 💻 **Simple CLI** - Easy `init`, `dev`, and `build` commands
-- 🌐 **Deploy Anywhere** - Deploy the generated sites anywhere (GitHub Pages, Netlify, Vercel, etc.)
+-   **Markdown First:** Write your content in standard Markdown with simple YAML frontmatter.
+-   **Beautiful Themes:** Comes with multiple built-in themes (`sky`, `ruby`, `retro`) and automatic light/dark mode support.
+-   **Fast & Lightweight:** Blazing fast static site generation with a minimal client-side footprint.
+-   **Rich Content:** Go beyond basic Markdown with custom components like callouts, cards, steps, tabs, and Mermaid diagrams.
+-   **Built-in Plugins:** SEO meta tags, sitemap, and analytics are all included out-of-the-box.
+-   **No-Style Pages:** Create completely custom pages (like landing pages) with full control over the HTML.
+-   **Customizable:** Easily extend or override styles with your own CSS and JavaScript.
+-   **Simple CLI:** A straightforward workflow with three main commands: `init`, `dev`, and `build`.
+-   **Deploy Anywhere:** The generated `site/` folder can be hosted on any static web host (GitHub Pages, Netlify, Vercel, etc.).
 
 ## Installation
+**Prerequisites:** [Node.js](https://nodejs.org/) (version 22.x or higher)
 
-### From npm
+### Quick Start: Your First Site in 60 Seconds
+
+No global installation is required. You can create and run your site in a new folder with one command.
 
 ```bash
-# Global installation (recommended)
-npm install -g @mgks/docmd
+# Create a new project in 'my-docs' and navigate into it
+npx @mgks/docmd init my-docs && cd my-docs
 
-# Local project installation
-npm install --save-dev @mgks/docmd
+# Start the development server
+npm start
 ```
 
-### Quick Start
+Your new documentation site is now running at `http://localhost:3000` *(or, at your selected or available port)*.
 
-```bash
-# Initialize a new documentation project
-docmd init
+### Global Installation
 
-# Start the development server
-docmd dev
+For frequent use, or if you prefer to have the command available system-wide, you can install `docmd` globally using npm.
 
-# Build for production
-docmd build
+```bash
+npm install -g @mgks/docmd
 ```
+After installation, you can run the `docmd` commands from any directory.
 
-### Documentation
+### Basic Workflow
 
-For complete documentation, visit **[docmd.mgks.dev](https://docmd.mgks.dev)**
+1.  **Initialize a Project:**
+    ```bash
+    docmd init
+    ```
+    This creates a `docs/` directory, a `docmd.config.js` file, and a sample `index.md` to get you started.
 
-## Contributing
+2.  **Start the Dev Server:**
+    ```bash
+    docmd dev
+    ```
+    This starts a live-reloading server to preview your site as you write.
 
-Contributions are welcome! Please check our [contributing guidelines](https://docmd.mgks.dev/contributing/) to get started.
+3.  **Build for Production:**
+    ```bash
+    docmd build
+    ```
+    This generates the complete, optimized static site into the `site/` directory, ready for deployment.
 
-1. Fork the repository
-2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/docmd.git`
-3. Install dependencies: `npm install`
-4. Make your changes and test them
-5. Submit a pull request
+## Documentation
 
-## License
+For a complete guide covering all features, including theming, custom containers, and plugin configuration, please visit the official documentation website: **[docmd.mgks.dev](https://docmd.mgks.dev)**.
+
+## Contributing
+
+We welcome contributions of all kinds! Whether it's reporting a bug, suggesting a feature, or submitting a pull request, your help is appreciated.
 
-`docmd` is licensed under the [MIT License](https://github.com/mgks/docmd/blob/main/LICENSE).
+1.  Fork the repository.
+2.  Clone your fork: `git clone https://github.com/YOUR_USERNAME/docmd.git`
+3.  Install dependencies: `npm install`
+4.  Make your changes and test them thoroughly.
+5.  Submit a pull request to the `main` branch.
+
+Please check our [contributing guidelines](https://docmd.mgks.dev/contributing/) for more detailed information.
 
 ## Support the Project
 
 If you find `docmd` useful, please consider:
 
-- Starring the repository on GitHub
-- Sharing it with others who might benefit
-- Reporting issues or submitting pull requests
+-   Starring the repository on GitHub.
+-   Sharing it with others who might benefit.
+-   Reporting issues or submitting pull requests.
+
+❤️ **[GitHub Sponsors](https://github.com/sponsors/mgks): Become a sponsor to support the ongoing development of `docmd`.**
+
+## License
 
-**[GitHub Sponsors](https://github.com/sponsors/mgks): Become a monthly or one-time GitHub sponsor to support docmd & other projects developed by [@mgks](https://mgks.dev).**
+Docmd is licensed under the [MIT License](https://github.com/mgks/docmd/blob/main/LICENSE).

package/bin/docmd.js

@@ -7,6 +7,7 @@ const { version } = require('../package.json');
 const { initProject } = require('../src/commands/init');
 const { buildSite } = require('../src/commands/build');
 const { startDevServer } = require('../src/commands/dev');
+const { printBanner } = require('../src/core/logger');
 
 // Helper function to find the config file
 const findConfigFile = () => {
@@ -52,6 +53,8 @@ program
   .option('--silent', 'Suppress log output')
   .action(async (options) => {
     try {
+      if (!options.silent) { printBanner(); }
+
       const originalLog = console.log;
       if (options.silent) { console.log = () => {}; }
 
@@ -68,7 +71,7 @@ program
 
     } catch (error) {
       console.error('❌ Build failed:', error.message);
-      console.error(error.stack);
+      // console.error(error.stack);
       process.exit(1);
     }
   });
@@ -83,6 +86,8 @@ program
   .option('--silent', 'Suppress log output')
   .action(async (options) => {
     try {
+      if (!options.silent) { printBanner(); }
+
       if (options.silent) {
         const originalLog = console.log;
         console.log = (message) => {
@@ -96,7 +101,7 @@ program
 
     } catch (error) {
       console.error('❌ Dev server failed:', error.message);
-      console.error(error.stack);
+      // console.error(error.stack);
       process.exit(1);
     }
   });

package/bin/postinstall.js

@@ -0,0 +1,14 @@
+// bin/postinstall.js
+
+const chalk = require('chalk');
+
+// This script runs after 'npm install', runs only when the user installs it globally and not in a CI environment
+
+if (process.env.npm_config_global && !process.env.CI) {
+  console.log(chalk.green('\n🎉 Thank you for installing docmd!'));
+  console.log('\nTo get started, run the following commands:');
+  console.log(`\n  ${chalk.cyan('docmd init my-awesome-docs')}`);
+  console.log(`  ${chalk.cyan('cd my-awesome-docs')}`);
+  console.log(`  ${chalk.cyan('npm start')}`);
+  console.log('\nFor complete documentation, visit: https://docmd.mgks.dev');
+}

package/config.js

@@ -169,7 +169,7 @@ module.exports = {
   // Sponsor Ribbon Configuration
   sponsor: {
     enabled: true,                    // Enable/disable the sponsor ribbon
-    title: 'Support docmd',     // Text to display on the ribbon
+    title: 'Sponsor',     // Text to display on the ribbon
     link: 'https://github.com/sponsors/mgks', // URL for the sponsor link
   },
 

package/docs/overview.md

@@ -3,7 +3,13 @@ title: "Minimalist Markdown Docs Generator"
 description: "Generate beautiful, lightweight static documentation sites directly from your Markdown files with docmd. Zero clutter, just content."
 ---
 
-# docmd
+```
+   _                 _ 
+ _| |___ ___ _____ _| |
+| . | . |  _|     | . |
+|___|___|___|_|_|_|___|
+
+```
 
 **Generate beautiful, lightweight static documentation sites directly from your Markdown files. Zero clutter, just content.**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mgks/docmd",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Generate beautiful, lightweight static documentation sites directly from your Markdown files. Zero clutter, just content.",
   "main": "src/index.js",
   "exports": {
@@ -15,6 +15,7 @@
   "scripts": {
     "start": "node ./bin/docmd.js dev",
     "build": "node ./bin/docmd.js build",
+    "postinstall": "node ./bin/postinstall.js",
     "lint": "eslint .",
     "format": "prettier --write .",
     "test": "echo \"Error: no test specified\" && exit 1"
@@ -41,6 +42,8 @@
   },
   "homepage": "https://github.com/mgks/docmd#readme",
   "dependencies": {
+    "@mgks/docmd": "^0.2.5",
+    "chalk": "^4.1.2",
     "chokidar": "^4.0.3",
     "commander": "^14.0.0",
     "ejs": "^3.1.9",

package/src/commands/build.js

@@ -6,6 +6,7 @@ const { loadConfig } = require('../core/config-loader');
 const { createMarkdownItInstance, processMarkdownFile, findMarkdownFiles } = require('../core/file-processor');
 const { generateHtmlPage, generateNavigationHtml } = require('../core/html-generator');
 const { renderIcon, clearWarnedIcons } = require('../core/icon-renderer');
+const { findPageNeighbors } = require('../core/navigation-helper');
 const { generateSitemap } = require('../plugins/sitemap');
 const { version } = require('../../package.json');
 const matter = require('gray-matter');
@@ -218,8 +219,12 @@ async function buildSite(configPath, options = { isDev: false, preserve: false,
 
       const finalOutputHtmlPath = path.join(OUTPUT_DIR, outputHtmlPath);
 
-      const depth = outputHtmlPath.split(path.sep).length - 1;
-      const relativePathToRoot = depth > 0 ? '../'.repeat(depth) : './';
+      let relativePathToRoot = path.relative(path.dirname(finalOutputHtmlPath), OUTPUT_DIR);
+      if (relativePathToRoot === '') {
+          relativePathToRoot = './';
+      } else {
+          relativePathToRoot = relativePathToRoot.replace(/\\/g, '/') + '/';
+      }
 
       let normalizedPath = path.relative(SRC_DIR, filePath).replace(/\\/g, '/');
       if (path.basename(normalizedPath) === 'index.md') {
@@ -247,74 +252,20 @@ async function buildSite(configPath, options = { isDev: false, preserve: false,
         config
       );
 
-      let prevPage = null;
-      let nextPage = null;
-      let currentPageIndex = -1;
-      
-      const flatNavigation = [];
-      
-      function createNormalizedPath(item) {
-        if (!item.path) return null;
-        return item.path.startsWith('/') ? item.path : '/' + item.path;
-      }
-      
-      function extractNavigationItems(items) {
-        if (!items || !Array.isArray(items)) return;
-        
-        for (const item of items) {
-          if (item.external) continue;
-          
-          if (item.path) {
-            let normalizedItemPath = createNormalizedPath(item);
-            if (item.children && !normalizedItemPath.endsWith('/')) {
-              normalizedItemPath += '/';
-            }
-            flatNavigation.push({
-              title: item.title,
-              path: normalizedItemPath,
-            });
-          }
-          
-          if (item.children && Array.isArray(item.children)) {
-            extractNavigationItems(item.children);
-          }
-        }
-      }
-      
-      extractNavigationItems(config.navigation);
-      
-      currentPageIndex = flatNavigation.findIndex(item => {
-        const itemPath = item.path;
-        const currentPagePath = normalizedPath;
-        if (itemPath === currentPagePath) {
-          return true;
-        }
-        if (itemPath.endsWith('/') && itemPath.slice(0, -1) === currentPagePath) {
-          return true;
-        }
-        if (currentPagePath.endsWith('/') && currentPagePath.slice(0, -1) === itemPath) {
-          return true;
-        }        
-        return false;
-      });
-      
-      if (currentPageIndex >= 0) {
-        if (currentPageIndex > 0) prevPage = flatNavigation[currentPageIndex - 1];
-        if (currentPageIndex < flatNavigation.length - 1) nextPage = flatNavigation[currentPageIndex + 1];
-      }
-      
+      // Find previous and next pages for navigation
+      const { prevPage, nextPage } = findPageNeighbors(config.navigation, normalizedPath);
+
       if (prevPage) {
-        const cleanPath = prevPage.path.startsWith('/') ? prevPage.path.substring(1) : prevPage.path;
-        prevPage.url = relativePathToRoot + (cleanPath.endsWith('/') ? cleanPath : cleanPath + '/');
-        if (prevPage.path === '/') prevPage.url = relativePathToRoot;
+        const cleanPath = prevPage.path.substring(1);
+        prevPage.url = relativePathToRoot + cleanPath;
       }
       
       if (nextPage) {
-        const cleanPath = nextPage.path.startsWith('/') ? nextPage.path.substring(1) : nextPage.path;
-        nextPage.url = relativePathToRoot + (cleanPath.endsWith('/') ? cleanPath : cleanPath + '/');
-        if (nextPage.path === '/') nextPage.url = relativePathToRoot;
+        const cleanPath = nextPage.path.substring(1);
+        nextPage.url = relativePathToRoot + cleanPath;
       }
 
+      // Log navigation paths for debugging
       const pageDataForTemplate = {
         content: htmlContent,
         pageTitle: pageFrontmatter.title || 'Untitled',

package/src/core/html-generator.js

@@ -1,4 +1,4 @@
-//
+// Source file from the docmd project — https://github.com/mgks/docmd
 
 const ejs = require('ejs');
 const path = require('path');

package/src/core/logger.js

@@ -0,0 +1,21 @@
+// Source file from the docmd project — https://github.com/mgks/docmd
+
+const chalk = require('chalk');
+
+const { version } = require('../../package.json');
+
+const printBanner = () => {
+  const logo = `
+                       
+${chalk.blue('     _                 _ ')}
+${chalk.blue('   _| |___ ___ _____ _| |')}
+${chalk.blue('  | . | . |  _|     | . |')}
+${chalk.blue('  |___|___|___|_|_|_|___|')}
+  `;
+
+  console.log(logo);
+  console.log(`   ${chalk.dim(`v${version}`)}`);
+  console.log(`\n`);
+};
+
+module.exports = { printBanner };

package/src/core/navigation-helper.js

@@ -0,0 +1,62 @@
+// Source file from the docmd project — https://github.com/mgks/docmd
+
+/**
+ * Flattens the navigation tree and finds the previous and next pages relative to the current page.
+ * @param {Array} navItems - The navigation array from config.
+ * @param {string} currentPagePath - The normalized path of the current page.
+ * @returns {{prevPage: object|null, nextPage: object|null}}
+ */
+function findPageNeighbors(navItems, currentPagePath) {
+  const flatNavigation = [];
+
+  // Recursive function to flatten the navigation tree
+  function extractNavigationItems(items) {
+    if (!items || !Array.isArray(items)) return;
+    
+    for (const item of items) {
+      if (item.external || !item.path || item.path === '#') {
+        // If it's a category with no path but has children, recurse into them
+        if (item.children && Array.isArray(item.children)) {
+          extractNavigationItems(item.children);
+        }
+        continue; // Skip external links and parent items without a direct path
+      }
+
+      let normalizedItemPath = item.path;
+
+      // Ensure it starts with a slash
+      if (!normalizedItemPath.startsWith('/')) {
+        normalizedItemPath = '/' + normalizedItemPath;
+      }
+
+      // Ensure it ends with a slash (unless it's the root path)
+      if (normalizedItemPath.length > 1 && !normalizedItemPath.endsWith('/')) {
+        normalizedItemPath += '/';
+      }
+
+      flatNavigation.push({
+        title: item.title,
+        path: normalizedItemPath,
+      });
+
+      if (item.children && Array.isArray(item.children)) {
+        extractNavigationItems(item.children);
+      }
+    }
+  }
+
+  extractNavigationItems(navItems);
+
+  const currentPageIndex = flatNavigation.findIndex(item => item.path === currentPagePath);
+
+  if (currentPageIndex === -1) {
+    return { prevPage: null, nextPage: null };
+  }
+
+  const prevPage = currentPageIndex > 0 ? flatNavigation[currentPageIndex - 1] : null;
+  const nextPage = currentPageIndex < flatNavigation.length - 1 ? flatNavigation[currentPageIndex + 1] : null;
+
+  return { prevPage, nextPage };
+}
+
+module.exports = { findPageNeighbors };