@mgks/docmd 0.2.7 → 0.2.8

package/.github/CONTRIBUTING.md

@@ -0,0 +1,129 @@
+# Contributing to docmd
+
+First off, thank you for considering contributing to `docmd`! It's people like you that make the open-source community such an amazing place to learn, inspire, and create.
+
+We welcome contributions of all kinds: bug fixes, new features, documentation improvements, or even just typo fixes.
+
+## ⚡ Quick Links
+
+*   [**Documentation**](https://docmd.mgks.dev) - Read the docs to understand how the tool works.
+*   [**GitHub Issues**](https://github.com/mgks/docmd/issues) - Browse existing bugs or feature requests.
+*   [**Discussions**](https://github.com/mgks/docmd/discussions) - Ask questions or share ideas.
+
+---
+
+## 🛠️ Development Setup
+
+`docmd` is a Node.js CLI tool. Developing it locally requires a slightly different setup than a standard web app.
+
+### Prerequisites
+*   **Node.js**: Version 22.x or higher.
+*   **npm**: Version 10.x or higher.
+
+### 1. Fork and Clone
+1.  Fork the repository to your GitHub account.
+2.  Clone your fork locally:
+    ```bash
+    git clone https://github.com/YOUR_USERNAME/docmd.git
+    cd docmd
+    ```
+
+### 2. Install Dependencies
+```bash
+npm install
+```
+
+### 3. Link for Local Development
+To test the CLI command (`docmd`) globally on your machine while modifying the source code, use `npm link`.
+
+```bash
+# inside the project root
+npm link
+```
+
+Now, when you run `docmd` in *any* terminal window, it will use the code from your local folder.
+
+### 4. Running the Dev Server
+We have a built-in test site located in the `docs/` folder (this is the documentation for docmd itself).
+
+To start the dev server and watch for changes:
+
+```bash
+# Method 1: Using the npm script (Recommended)
+npm start
+
+# Method 2: If you have linked the package
+docmd dev
+```
+
+### 5. Developer Mode (Important)
+By default, `docmd` only watches the user's content files. To make `docmd` watch **its own internal source code** (templates, css, core logic) and trigger a rebuild when you edit them, set the environment variable:
+
+```bash
+# Mac/Linux
+export DOCMD_DEV=true
+npm start
+
+# Windows (PowerShell)
+$env:DOCMD_DEV="true"
+npm start
+```
+
+---
+
+## 📂 Project Structure
+
+Here is a map of the codebase to help you navigate:
+
+```text
+bin/
+  └── docmd.js          # The CLI entry point
+src/
+  ├── commands/         # Logic for 'init', 'build', 'dev'
+  ├── core/
+  │   ├── config-loader.js   # Loads docmd.config.js
+  │   ├── config-validator.js # Validates config structure
+  │   ├── file-processor.js  # Orchestrates file reading
+  │   ├── html-generator.js  # Injects content into EJS templates
+  │   └── markdown/          # The Core Parsing Engine
+  │       ├── containers.js  # Callout/Card definitions
+  │       ├── rules.js       # Complex logic (Tabs, Changelogs)
+  │       └── setup.js       # MarkdownIt configuration
+  ├── plugins/          # Built-in plugins (SEO, Sitemap)
+  ├── templates/        # EJS HTML templates
+  └── assets/           # Internal CSS and JS (Themes)
+docs/                   # The documentation site content
+site/                   # The generated output folder (gitignored)
+```
+
+---
+
+## 🚀 Submitting a Pull Request
+
+1.  **Create a Branch:** Always create a new branch for your changes.
+    *   `feat/my-new-feature`
+    *   `fix/bug-description`
+    *   `docs/update-readme`
+2.  **Make Changes:** Write clear, concise code.
+3.  **Test:**
+    *   Run `docmd build` to ensure the build process finishes without errors.
+    *   Verify your changes visually by running `docmd dev`.
+4.  **Commit:** We prefer [Conventional Commits](https://www.conventionalcommits.org/).
+    *   `feat: add search bar`
+    *   `fix: resolve css overflow in tables`
+    *   `docs: fix typo in readme`
+5.  **Push & Open PR:** Push your branch to your fork and open a Pull Request against the `main` branch of `mgks/docmd`.
+
+---
+
+## 🎨 Style Guidelines
+
+*   **Linting:** Please ensure your code follows the existing style. (We use standard ESLint/Prettier configurations).
+*   **No-Style:** If modifying `no-style` templates, ensure no external CSS is injected unless requested.
+*   **Compatibility:** `docmd` aims to be lightweight. Avoid adding heavy dependencies unless absolutely necessary.
+
+---
+
+## 🤝 Community
+
+Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.

package/.github/workflows/publish.yml

@@ -39,7 +39,9 @@ jobs:
       # --- Publish to GitHub Packages (GPR) ---
       # ----------------------------------------
       - name: Configure NPM for GitHub Packages registry
-        run: echo "//npm.pkg.github.com/:_authToken=${{ secrets.GITHUB_TOKEN }}" > ~/.npmrc
+        run: |
+          echo "@mgks:registry=https://npm.pkg.github.com" > ~/.npmrc
+          echo "//npm.pkg.github.com/:_authToken=${{ secrets.GITHUB_TOKEN }}" >> ~/.npmrc
 
       - name: Publish to GitHub Packages
         run: npm publish

package/README.md

@@ -1,123 +1,160 @@
 <p align="center">
-  <img src="https://github.com/mgks/docmd/blob/main/src/assets/images/docmd-logo.png" alt="docmd logo" width="70" />
-  <br />
-  <img src="https://github.com/mgks/docmd/blob/main/src/assets/images/docmd-logo-light.png" alt="docmd dark logo" width="180" />
+  <br>
+  <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" />
+  </a>
 </p>
 
 <p align="center">
-  <b>Generate beautiful, lightweight static documentation sites from Markdown files.</b>
-  <br>Zero clutter, just content.
+  <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 align="center">
-  <a href="https://www.npmjs.com/package/@mgks/docmd"><img src="https://img.shields.io/npm/v/@mgks/docmd.svg" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/@mgks/docmd"><img src="https://img.shields.io/npm/d18m/@mgks/docmd.svg" 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" 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=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://github.com/mgks/docmd/stargazers"><img src="https://img.shields.io/github/stars/mgks/docmd?style=flat-square&logo=github" alt="stars"></a>
 </p>
 
-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.
+<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://github.com/mgks/docmd/issues"><b>Report Bug</b></a>
+</p>
+
+<br>
 
-**:rocket: [Live Preview](https://docmd.mgks.dev): Official documentation site powered by `docmd`.**
+<p align="center">
+  <img width="2856" height="1558" alt="519536477-8d948e18-8e2d-420d-8902-96e1aafab1ba-modified" src="https://github.com/user-attachments/assets/5b883c80-8357-46e8-9adb-84e38a0da64c" />
+  <sup><i>docmd noStyle page preview in dark mode</i></sup>
+</p>
 
-## Key Features
+## 🚀 Why docmd?
 
--   **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.
--   **Smart CLI:** Intelligent configuration validation catches typos and errors early. Simple workflow with `init`, `dev`, and `build`.
--   **Deploy Anywhere:** The generated `site/` folder can be hosted on any static web host (GitHub Pages, Netlify, Vercel, etc.).
+Most documentation tools today are too heavy (React hydration, massive bundles) or require ecosystems you don't use (Python/Ruby).
 
-## Installation and Usage
+**docmd** fills the gap. It is a native Node.js tool that generates **pure, static HTML**.
 
-**Prerequisites:** [Node.js](https://nodejs.org/) (version 22.x or higher) is required.
+*   ⚡ **Blazing Fast:** No hydration delay. Instant page loads.
+*   🛠 **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.
 
-### Global Installation (Recommended)
+## 🏁 Quick Start
 
-This is the recommended approach for developers who will use `docmd` across multiple projects. It makes the `docmd` command available system-wide.
+You don't need to install anything globally to try it out.
 
-**1. Install Globally:**
 ```bash
-npm install -g @mgks/docmd
+# 1. Initialize a new project
+npx @mgks/docmd init my-docs
+
+# 2. Enter directory
+cd my-docs
+
+# 3. Start the dev server
+npm start
+```
+
+**Dev server output:**
+
+```
+                       
+     _                 _ 
+   _| |___ ___ _____ _| |
+  | . | . |  _|     | . |
+  |___|___|___|_|_|_|___|
+  
+   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.
 ```
 
-**2. Basic Workflow:**
-Once installed, you can use the `docmd` command directly in any project folder.
+## ✨ Features
 
-*   **Initialize a Project:**
-    ```bash
-    # This creates docs/, docmd.config.js, and a sample index.md
-    docmd init
-    ```
+| 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. |
+| **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. |
 
-*   **Start the Dev Server:**
-    ```bash
-    # Starts a live-reloading server at http://localhost:3000
-    docmd dev
-    ```
+## 🆚 Comparison
 
-*   **Build for Production:**
-    ```bash
-    # Generates the static site into the `site/` directory
-    docmd build
-    ```
+How does `docmd` stack up against the giants?
 
-### Quick Start (Alternative)
+| 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 |
 
-If you prefer not to install packages globally, you can use `npx` to run `docmd` on-demand. This is a great way to try it out or use it in a single project.
+👉 *[Read the full comparison](https://docmd.mgks.dev/comparison/)*
 
-1.  **Create and Initialize Your Project:**
-    This command will download the latest version, create a `my-docs` folder, and set up the project files inside it.
-    ```bash
-    npx @mgks/docmd init my-docs
-    ```
+## 📦 Installation
 
-2.  **Start the Development Server:**
-    Navigate into your new project and use `npx` again to start the server.
-    ```bash
-    cd my-docs
-    npx @mgks/docmd dev
-    ```
+For frequent use, install globally:
 
-Your new documentation site is now running at `http://localhost:3000`.
+```bash
+npm install -g @mgks/docmd
+```
 
-## Documentation
+### Commands
 
-For a complete guide, visit the official documentation: **[docmd.mgks.dev](https://docmd.mgks.dev)**.
+*   `docmd init` - Create a new documentation project.
+*   `docmd dev` - Start the live-reloading local server.
+*   `docmd build` - Generate static files to `site/` for deployment.
 
-### Essential Topics
--   **[Getting Started](https://docmd.mgks.dev/getting-started/installation/):** Installation and basic CLI usage.
--   **[Custom Containers](https://docmd.mgks.dev/content/containers/):** How to use Callouts, Cards, Tabs, and Steps.
--   **[Theming](https://docmd.mgks.dev/theming/):** Customizing colors, dark mode, and adding your logo.
--   **[Plugins](https://docmd.mgks.dev/plugins/):** SEO, Analytics, and Sitemap configuration.
--   **[Recipes](https://docmd.mgks.dev/recipes/):** Step-by-step guides for common tasks like Custom Fonts and Landing Pages.
--   **[Comparison](https://docmd.mgks.dev/comparison/):** How `docmd` stacks up against Docusaurus, MkDocs, and others.
+## 🎨 Themes
 
-## Contributing
+Switching themes is as easy as changing one line in your `docmd.config.js`.
 
-We welcome contributions of all kinds! Whether it's reporting a bug, suggesting a feature, or submitting a pull request, your help is appreciated.
+```javascript
+module.exports = {
+  theme: {
+    name: 'sky', // Options: 'default', 'sky', 'ruby', 'retro'
+    defaultMode: 'dark'
+  }
+}
+```
 
-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.
+## 🤝 Contributing
 
-Please check our [contributing guidelines](https://docmd.mgks.dev/contributing/) for more detailed information.
+We welcome contributions! Please see our [Contribution Guidelines](.github/CONTRIBUTING.md) for details.
 
-## Support the Project
+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.
 
-If you find `docmd` useful, please consider:
+## ❤️ Support
 
--   Starring the repository on GitHub.
--   Sharing it with others who might benefit.
--   Reporting issues or submitting pull requests.
+This project is open source and free to use. If you find it valuable, please consider:
 
-❤️ **[GitHub Sponsors](https://github.com/sponsors/mgks): Become a sponsor to support the ongoing development of `docmd`.**
+1.  ⭐️ **Starring the repo** on GitHub (it helps a lot!)
+2.  ☕ **[Sponsoring the project](https://github.com/sponsors/mgks)** to support ongoing development.
 
-## License
+## 📄 License
 
-Docmd is licensed under the [MIT License](https://github.com/mgks/docmd/blob/main/LICENSE).
+Distributed under the MIT License. See `LICENSE` for more information.

package/config.js

@@ -123,6 +123,8 @@ module.exports = {
               { 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: 'logs' },
               { title: 'Buttons', path: '/content/containers/buttons', icon: 'mouse-pointer-click' },
               { title: 'Nested Containers', path: '/content/containers/nested-containers', icon: 'folder-tree' },
             ]

package/docs/content/containers/changelogs.md

@@ -0,0 +1,128 @@
+---
+title: "Container: Changelogs"
+description: "Create a beautiful, timeline-style version history for your project."
+---
+
+# Changelog Container
+
+The `changelog` container allows you to present version history and release notes in a clean, timeline layout. It separates metadata (dates/versions) from the narrative content, making it easy for users to scan updates.
+
+## Usage
+
+The changelog container uses a specific syntax where entries are separated by `==` markers.
+
+::: callout info
+Container blocks (like `::: changelog`) should be preceded by a blank line.
+:::
+
+**Syntax:**
+```markdown
+::: changelog
+
+== Version/Date String
+Content for this version.
+Supports **Markdown**, lists, and other containers.
+
+== Next Version/Date String
+Content for the next version.
+
+:::
+```
+
+**`==`**: This marker denotes the start of a new entry. Everything after `==` on the same line is treated as the "Date" or "Version" badge on the left side of the timeline.
+
+---
+
+## Examples
+
+### Basic Version History
+
+**Code:**
+```markdown
+::: changelog
+
+== v2.0.0 (2025-01-15)
+### Major Update 🚀
+We completely rewrote the core engine for better performance.
+
+*   Added new plugin system
+*   Improved build speed by 50%
+
+== v1.1.0 (2024-12-01)
+### Feature Drop
+Added support for custom themes and dark mode.
+
+== v1.0.0 (2024-11-10)
+Initial public release.
+:::
+```
+
+**Rendered Preview:**
+
+::: changelog
+
+== v2.0.0 (2025-01-15)
+### Major Update 🚀
+We completely rewrote the core engine for better performance.
+
+*   Added new plugin system
+*   Improved build speed by 50%
+
+== v1.1.0 (2024-12-01)
+### Feature Drop
+Added support for custom themes and dark mode.
+
+== v1.0.0 (2024-11-10)
+Initial public release.
+:::
+
+### Changelog with Nested Elements
+
+You can put anything inside a changelog entry, including callouts and code blocks.
+
+**Code:**
+````markdown
+::: changelog
+
+== v3.0.0-beta
+### The Future is Here
+
+::: callout warning Breaking Changes
+This release changes the config format. Please update your `docmd.config.js`.
+:::
+
+**New Config Example:**
+```javascript
+module.exports = {
+  version: 3,
+  // ...
+}
+```
+
+== v2.5.0
+Maintenance release with bug fixes.
+:::
+````
+
+**Rendered Preview:**
+
+::: changelog
+
+== v3.0.0-beta
+### The Future is Here
+
+::: callout warning Breaking Changes
+This release changes the config format. Please update your `docmd.config.js`.
+:::
+
+**New Config Example:**
+```javascript
+module.exports = {
+  version: 3,
+  // ...
+}
+```
+
+== v2.5.0
+Maintenance release with bug fixes.
+:::

package/docs/content/containers/collapsible.md

@@ -0,0 +1,89 @@
+---
+title: "Container: Collapsible"
+description: "Create accordion-style toggleable sections for FAQs, spoilers, or advanced details."
+---
+
+# Collapsible Container
+
+The `collapsible` container creates an accordion-style block that can be toggled open or closed. This is perfect for FAQs, "spoiler" content, or hiding complex details that aren't immediately necessary.
+
+## Usage
+
+The syntax allows you to define the title and the default state (open or closed).
+
+**Syntax:**
+```markdown
+::: collapsible [open] Title Text Here
+The hidden content goes here.
+:::
+```
+
+-   **`open`**: (Optional) If included, the section will be expanded by default on page load.
+-   **`Title Text Here`**: The text displayed on the clickable bar. If omitted, it defaults to "Click to expand".
+
+---
+
+## Examples
+
+### Basic Collapsible (Closed by Default)
+
+Use this for content that should be hidden initially, like lengthy code examples or optional details.
+
+**Code:**
+```markdown
+::: collapsible View Advanced Configuration
+Here are the advanced settings for power users:
+*   `memory_limit`: Set the max heap size.
+*   `threads`: Number of worker threads.
+:::
+```
+
+**Rendered Preview:**
+
+::: collapsible View Advanced Configuration
+Here are the advanced settings for power users:
+*   `memory_limit`: Set the max heap size.
+*   `threads`: Number of worker threads.
+:::
+
+### Default Open
+
+Use the `open` keyword if you want the content visible but capable of being tucked away.
+
+**Code:**
+```markdown
+::: collapsible open Important Notice
+This content is visible immediately but can be collapsed if it takes up too much space.
+:::
+```
+
+**Rendered Preview:**
+
+::: collapsible open Important Notice
+This content is visible immediately but can be collapsed if it takes up too much space.
+:::
+
+### FAQ Pattern
+
+Collapsibles are ideal for Frequently Asked Questions.
+
+**Code:**
+```markdown
+::: collapsible Is docmd free to use?
+**Yes!** docmd is 100% open-source and free under the MIT license.
+:::
+
+::: collapsible Can I host it on GitHub Pages?
+Absolutely. The `build` command generates static HTML files that work perfectly on GitHub Pages, Netlify, or Vercel.
+:::
+```
+
+**Rendered Preview:**
+
+::: collapsible Is docmd free to use?
+**Yes!** docmd is 100% open-source and free under the MIT license.
+:::
+
+::: collapsible Can I host it on GitHub Pages?
+Absolutely. The `build` command generates static HTML files that work perfectly on GitHub Pages, Netlify, or Vercel.
+:::

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mgks/docmd",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Generate beautiful, lightweight static documentation sites directly from your Markdown files. Zero clutter, just content.",
   "main": "src/index.js",
   "exports": {
@@ -42,7 +42,6 @@
   },
   "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",