@mgks/docmd 0.2.4 → 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,69 +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.
 
-## Features
+**:rocket: [Live Preview](https://docmd.mgks.dev): Official documentation site powered by `docmd`.**
 
-- 📝 **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.).
+## Key Features
+
+-   **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)
+
+### Quick Start: Your First Site in 60 Seconds
 
-### From npm
+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 [me](https://mgks.dev).**
+Docmd is licensed under the [MIT License](https://github.com/mgks/docmd/blob/main/LICENSE).

package/assets/css/welcome.css

@@ -1,6 +1,6 @@
 /*
  * Source file from the docmd project — https://github.com/mgks/docmd
- * Configuration for the docmd project's own documentation
+ * Welcome page stylesheet for the docmd project's own documentation
  */
 
 :root,html[data-theme=light]{--primary-color:#047bf1;--primary-hover:#026ed9;--text-color:#333;--text-light:#666;--bg-color:#fff;--bg-secondary:#f8f9fa;--border-color:#eaeaea}.theme-toggle,body{color:var(--text-color);display:flex}.logo-text,h1{font-weight:700}.install-code pre,.logo-text{font-family:'PT Mono',monospace}:root{--shadow-color:#00000014;--container-padding:5rem}@media (prefers-color-scheme:dark){:root{--primary-color:#047bf1;--primary-hover:#026ed9;--text-color:#e0e0e0;--text-light:#aaa;--bg-color:#121212;--bg-secondary:#1e1e1e;--border-color:#333;--shadow-color:#0000004d}}[data-theme=light]{--shadow-color:#00000059}[data-theme=dark]{--primary-color:#1955b6;--primary-hover:#084dbd;--text-color:#e0e0e0;--text-light:#aaa;--bg-color:#121212;--bg-secondary:#1e1e1e;--border-color:#333;--shadow-color:#000000de}*{margin:0;padding:0;box-sizing:border-box}body{font-family:Inter,-apple-system,BlinkMacSystemFont,sans-serif;line-height:1.5;background-color:var(--bg-color);height:100vh;overflow:hidden}.landing-container{display:flex;width:100%;height:100%;padding:0 var(--container-padding);max-width:1600px;margin:0 auto}.content-side{flex:1;padding:3rem 2rem 3rem 0;display:flex;flex-direction:column;justify-content:center}.preview-side{flex:1;display:flex;align-items:center;justify-content:flex-start;position:relative;overflow:visible}.header-top{position:absolute;top:2rem;right:3rem;z-index:100}.theme-toggle{background:var(--bg-secondary);border:1px solid var(--border-color);width:40px;height:40px;border-radius:50%;align-items:center;justify-content:center;cursor:pointer;transition:.2s}.theme-toggle:hover{background:var(--border-color)}.logo{margin-bottom:1.5rem;display:flex;align-items:center}.buttons,.features,.install-section,.tagline{margin-bottom:2rem}.logo svg{height:48px;width:auto}.logo-text{font-size:2em;margin-left:.25em}h1{font-size:3rem;margin-bottom:1rem;letter-spacing:-.02em}.tagline{font-size:1.25rem;color:var(--text-light);font-weight:400}.btn-primary,.feature-icon{background-color:var(--primary-color);color:#fff}.features{display:grid;grid-template-columns:repeat(2,1fr);gap:1.5rem}.feature{display:flex;align-items:flex-start;gap:.75rem}.feature-icon{width:32px;height:32px;border-radius:6px;display:flex;align-items:center;justify-content:center;flex-shrink:0}.feature-text{font-size:.9rem}.feature-text strong{display:block;margin-bottom:.25rem}.buttons{display:flex;gap:1rem}.btn{display:inline-flex;align-items:center;gap:.5rem;padding:.75rem 1.5rem;border-radius:8px;font-weight:600;font-size:1rem;text-decoration:none;transition:.2s}.btn-primary{border:none}.btn-secondary,.install-code pre{background-color:var(--bg-secondary);border:1px solid var(--border-color)}.btn-primary:hover{background-color:var(--primary-hover)}.btn-secondary{color:var(--text-color)}.btn-secondary:hover{background-color:var(--border-color)}.social-links{display:flex;gap:1rem;padding:0 .25em}.social-link{color:var(--text-light);transition:color .2s}.social-link:hover{color:var(--primary-color)}.preview-stack{position:relative;width:100%;height:400px;transform:translateX(15%);perspective:1000px}.preview-image{position:absolute;width:100%;max-width:700px;height:400px;border-radius:20px;box-shadow:0 25px 50px -12px var(--shadow-color);transition:.3s;overflow:hidden}.preview-image img{width:100%;height:100%;object-fit:cover;object-position:left top;border-radius:8px;pointer-events:none}.preview-image.top{z-index:3;transform:rotate(3deg) translateY(-10%) translateX(7%)}.preview-image.middle{z-index:2;transform:rotate(-3deg) translateY(1%) translateX(-2%)}.preview-image.bottom{z-index:1;transform:rotate(-8deg) translateY(10%) translateX(-10%)}[data-theme=dark] .preview-image .dark-img,[data-theme=light] .preview-image .light-img{display:block}[data-theme=dark] .preview-image .light-img,[data-theme=light] .preview-image .dark-img{display:none}@media (max-width:1400px){:root{--container-padding:3rem}.preview-stack{transform:translateX(15%)}}@media (max-width:1200px){:root{--container-padding:2rem}.preview-side{display:none}.content-side{max-width:100%;padding:3rem 0}.header-top{right:2rem}}@media (max-width:768px){:root{--container-padding:1.5rem}body{overflow:auto}.content-side{padding:2rem 0}.features{grid-template-columns:1fr}.buttons{flex-direction:column}.header-top{padding:1rem 0;text-align:center;right:1rem}h1{font-size:2.5rem}.tagline{font-size:1em;font-weight:500}.landing-container{padding:1rem;flex-direction:column}}.social-links .lucide-heart-handshake{color:#cd2727}.install-code{position:relative;display:inline-block}.install-code pre{border-radius:8px;padding:1rem 3.5rem 1rem 1rem;margin:0;font-size:.9rem;color:var(--text-color)}.install-code code{background:0 0;padding:0;color:inherit}.copy-button{position:absolute;top:.5rem;right:.5rem;background:var(--bg-color);border:1px solid var(--border-color);border-radius:4px;padding:.5rem;cursor:pointer;transition:.2s;color:var(--text-light)}.copy-button:hover{background:var(--border-color);color:var(--text-color)}

package/bin/docmd.js

@@ -1,10 +1,28 @@
 #!/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 { 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 = () => {
+  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();
 
@@ -15,7 +33,7 @@ program
 
 program
   .command('init')
-  .description('Initialize a new docmd project (creates docs/ and config.js)')
+  .description('Initialize a new docmd project (creates docs/ and config file)')
   .action(async () => {
     try {
       await initProject();
@@ -28,20 +46,32 @@ program
 
 program
   .command('build')
-  .description('Build the static site from Markdown files and config.js')
-  .option('-c, --config <path>', 'Path to config.js file', 'config.js')
+  .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 {
-      console.log('🚀 Starting build process...');
-      await buildSite(options.config, { 
+      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('✅ Build complete! Site generated in `site/` directory.');
+
+      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);
+      // console.error(error.stack);
       process.exit(1);
     }
   });
@@ -49,15 +79,29 @@ program
 program
   .command('dev')
   .description('Start a live preview development server')
-  .option('-c, --config <path>', 'Path to config.js file', 'config.js')
+  .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 {
-      await startDevServer(options.config, { preserve: options.preserve });
+      if (!options.silent) { printBanner(); }
+
+      if (options.silent) {
+        const originalLog = console.log;
+        console.log = (message) => {
+          if (message && message.includes('Dev server started at')) {
+            originalLog(message);
+          }
+        };
+      }
+      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);
+      // 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

@@ -112,6 +112,7 @@ module.exports = {
           { title: 'Frontmatter', path: '/content/frontmatter', icon: 'file-text' },
           { title: 'Markdown Syntax', path: '/content/markdown-syntax', icon: 'code-2' },
           { title: 'Images', path: '/content/images', icon: 'image' },
+          { title: 'Mermaid Diagrams', path: '/content/mermaid', icon: 'network' },
           {
             title: 'Custom Containers',
             path: '/content/containers/',
@@ -163,10 +164,12 @@ module.exports = {
       { title: 'Issues', path: 'https://github.com/mgks/docmd/issues', icon: 'badge-alert', external: true }
   ],
 
+  pageNavigation: true, // Enable previous / next page navigation at the bottom of each page
+
   // 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/cli-commands.md

@@ -20,9 +20,9 @@ docmd init
 This command creates the basic file and directory structure required for a `docmd` project:
 *   `docs/`: A directory to store your Markdown source files.
     *   `docs/index.md`: A sample Markdown file.
-*   `config.js`: The main configuration file for your site, pre-filled with default settings.
+*   `docmd.config.js`: The main configuration file for your site, pre-filled with default settings.
 
-If a `docs/` directory or `config.js` file already exists, `docmd init` will typically warn you and avoid overwriting them to prevent accidental data loss.
+If a `docs/` directory or `docmd.config.js` file already exists, `docmd init` will typically warn you and avoid overwriting them to prevent accidental data loss.
 
 **Options:**
 This command currently does not take any options.
@@ -37,7 +37,7 @@ docmd build [options]
 ```
 
 **Description:**
-The `build` command reads your Markdown files from the source directory (specified by `srcDir` in `config.js`, defaults to `docs/`), processes them along with your `config.js`, and generates a complete static website in the output directory (specified by `outputDir` in `config.js`, defaults to `site/`).
+The `build` command reads your Markdown files from the source directory (specified by `srcDir` in `docmd.config.js`, defaults to `docs/`), processes them along with your `docmd.config.js`, and generates a complete static website in the output directory (specified by `outputDir` in `docmd.config.js`, defaults to `site/`).
 
 The output `site/` directory contains all the HTML, CSS, JavaScript, and other assets needed to deploy your documentation.
 
@@ -46,14 +46,16 @@ By default, the build process will update all assets to ensure you have the late
 **Options:**
 
 *   `-c, --config <path>`
-    *   **Default:** `config.js`
-    *   **Description:** Specifies the path to the configuration file. Useful if your config file is not named `config.js` or is not in the project root.
-    *   **Example:** `docmd build --config my.docmd.config.js`
+    *   **Default:** `docmd.config.js` or `config.js`
+    *   **Description:** Specifies the path to the configuration file.
 
 *   `-p, --preserve`
     *   **Default:** `false`
-    *   **Description:** Preserves existing asset files instead of updating them. Use this flag if you've customized any of the default assets and want to keep your modifications.
-    *   **Example:** `docmd build --preserve`
+    *   **Description:** Preserves existing asset files instead of updating them.
+
+*   `--silent`
+    *   **Default:** `false`
+    *   **Description:** Suppresses most log output in the console. Useful for running in automated environments.
 
 ## `docmd dev`
 
@@ -68,7 +70,7 @@ docmd dev [options]
 The `dev` command is essential for writing and previewing your documentation. It:
 1.  Performs an initial build of your site.
 2.  Starts a local web server (usually on `http://localhost:3000`).
-3.  Watches your source files (`docs/` directory, `config.js`, and internal `docmd` theme assets) for changes.
+3.  Watches your source files (`docs/` directory, `docmd.config.js`, and internal `docmd` theme assets) for changes.
 4.  When a change is detected, it automatically rebuilds the necessary parts of your site and triggers a live reload in your browser.
 
 This provides a fast feedback loop, allowing you to see your changes almost instantly.
@@ -76,14 +78,21 @@ This provides a fast feedback loop, allowing you to see your changes almost inst
 **Options:**
 
 *   `-c, --config <path>`
-    *   **Default:** `config.js`
+    *   **Default:** `docmd.config.js` or `config.js`
     *   **Description:** Specifies the path to the configuration file.
-    *   **Example:** `docmd dev --config my.docmd.config.js`
+
+*   `--port <number>`
+    *   **Default:** `3000`
+    *   **Description:** Specifies the port for the development server. If the port is in use, docmd will automatically try the next available one.
+    *   **Example:** `docmd dev --port 8080`
 
 *   `-p, --preserve`
     *   **Default:** `false`
-    *   **Description:** Preserves existing asset files instead of updating them. Use this flag if you've customized any of the default assets and want to keep your modifications.
-    *   **Example:** `docmd dev --preserve`
+    *   **Description:** Preserves existing asset files instead of updating them.
+
+*   `--silent`
+    *   **Default:** `false`
+    *   **Description:** Suppresses most log output in the console. Useful for running in automated environments.
 
 **Note:** The development server starts on port 3000 by default. If port 3000 is already in use, the server will automatically try the next available port (3001, 3002, etc.) until it finds an open port.
 

package/docs/configuration.md

@@ -1,16 +1,15 @@
 ---
 title: "Configuration"
-description: "Detailed explanation of all options available in the docmd config.js file, including logo, theming, plugins, and more."
+description: "Detailed explanation of all options available in the docmd config file, including logo, theming, plugins, and more."
 ---
 
-# Configuration (`config.js`)
+# Configuration (`docmd.config.js`)
 
-`docmd` uses a `config.js` file in the root of your documentation project to control various aspects of your site. This file should export a JavaScript object containing your configuration options.
+`docmd` uses a `docmd.config.js` file in the root of your project... For backward compatibility, it will fall back to using `config.js` if `docmd.config.js` is not found.
 
-## Example `config.js` Structure:
+## Example `docmd.config.js` Structure:
 
 ```javascript
-// config.js
 module.exports = {
   siteTitle: 'My Awesome Project Docs',
   logo: {

package/docs/content/frontmatter.md

@@ -52,6 +52,14 @@ Examples of custom fields you *might* add (these are not built-in features):
 *   `tags`: ["tag1", "tag2"]
 *   `permalink`: "https://example.com/your-canonical-url/" (Sets the canonical URL for SEO purposes)
 
+## Page-Specific Behavior Fields
+
+*   **`toc`** (Boolean, Optional)
+    *   **Purpose:** Controls the visibility of the "On This Page" table of contents sidebar.
+    *   **Default:** `true` (TOC is visible if the page has headings).
+    *   **Usage:** Set to `false` to completely hide the TOC sidebar for a specific page. This is useful for landing pages or pages with minimal content.
+    *   **Example:** `toc: false`
+
 ## Example Usage
 
 Consider a file named `docs/guides/installation.md`:

package/docs/content/index.md

@@ -12,6 +12,7 @@ docmd uses Markdown files to create beautiful documentation. This section covers
 - [**Frontmatter**](/content/frontmatter/) - Learn how to add metadata to your pages
 - [**Markdown Syntax**](/content/markdown-syntax/) - Basic and advanced Markdown features
 - [**Images**](/content/images/) - How to add and style images in your documentation
+- [**Mermaid Diagrams**](/content/mermaid/) - Create beautiful diagrams and flowcharts with Mermaid
 - [**Custom Containers**](/content/custom-containers/) - Special content blocks like callouts and cards
 - [**noStyle Pages**](/content/no-style-pages/) - Create custom standalone pages with complete HTML control