@mgks/docmd 0.2.6 → 0.2.7

package/.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,48 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at hello@mgks.dev.
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,58 @@
+name: 🐞 Bug Report
+description: Create a report to help us improve docmd
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: input
+    id: version
+    attributes:
+      label: docmd version
+      description: What version of docmd are you using? (e.g. 0.2.6)
+      placeholder: 0.2.6
+    validations:
+      required: true
+  - type: input
+    id: node-version
+    attributes:
+      label: Node.js version
+      placeholder: v20.x
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: OS
+      options:
+        - macOS
+        - Windows
+        - Linux
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of what the bug is.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Please provide the steps to reproduce the behavior.
+      placeholder: |
+        1. Run 'docmd init'
+        2. Add configuration...
+        3. Run 'docmd build'
+        4. See error...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: A clear and concise description of what you expected to happen.

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,27 @@
+name: 💡 Feature Request
+description: Suggest an idea for this project
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a new feature!
+  - type: textarea
+    id: problem
+    attributes:
+      label: Is your feature request related to a problem?
+      description: A clear and concise description of what the problem is.
+      placeholder: I'm always frustrated when...
+  - type: textarea
+    id: solution
+    attributes:
+      label: Describe the solution you'd like
+      description: A clear and concise description of what you want to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Describe alternatives you've considered
+      description: A clear and concise description of any alternative solutions or features you've considered.

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+## Description
+<!-- Please include a summary of the change and which issue is fixed. -->
+
+Fixes # (issue)
+
+## Type of change
+- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
+- [ ] ✨ New feature (non-breaking change which adds functionality)
+- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] 📝 Documentation update
+
+## Checklist:
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings

package/.github/SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.2.x   | :white_check_mark: |
+| 0.1.x   | :x:                |
+
+## Reporting a Vulnerability
+
+Use this section to tell people how to report a vulnerability.
+
+Please do not report security vulnerabilities through public GitHub issues.
+
+If you have discovered a security vulnerability in `docmd`, please email hello@mgks.dev.
+
+We will do our best to respond within 48 hours.

package/.github/workflows/publish.yml

@@ -2,83 +2,46 @@ name: Publish Package to NPM and GitHub Packages
 
 on:
   release:
-    types: [created] # [created, published] Triggers when a new GitHub Release is created or published
-  workflow_dispatch: # Allows manual triggering for testing
+    types: [published]
+  workflow_dispatch:
 
 jobs:
   publish:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      packages: write # Required for GitHub Packages
+      packages: write
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
-        # Your package.json in the workspace should now have name: "@mgks/docmd"
 
-      - name: Set up Node.js (common for all steps)
+      - name: Set up Node.js v22
         uses: actions/setup-node@v4
         with:
           node-version: '22'
-          cache: 'npm' # Cache npm dependencies
+          cache: 'npm'
 
       - name: Install dependencies
         run: npm ci
 
-      # Optional: Run build script if you have one for the package itself
-      # - name: Build package
-      #   run: npm run build
-
-      # Optional: Run tests
-      # - name: Test package
-      #   run: npm test
-
+      # ------------------------------------------
       # --- Publish to NPM Registry (npmjs.com) ---
-      - name: Set up Node.js for npmjs.com
-        uses: actions/setup-node@v4
-        with:
-          node-version: '22' # Redundant if already set, but harmless
-          registry-url: 'https://registry.npmjs.org/'
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} # Configures .npmrc for npmjs.com
+      # ------------------------------------------
+      - name: Configure NPM for public registry
+        run: echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > ~/.npmrc
 
-      # No need to change package.json name if it's already @mgks/docmd
-      # Just ensure no GPR-specific publishConfig is present
-      - name: Prepare package.json for npmjs.com
-        run: |
-          echo "package.json for npmjs.com publishing (should be @mgks/docmd):"
-          cat package.json
-          # Remove publishConfig if it exists, just in case
-          if jq -e '.publishConfig' package.json > /dev/null; then
-            echo "Removing publishConfig for npmjs.com publish"
-            jq 'del(.publishConfig)' package.json > package_temp.json && mv package_temp.json package.json
-          else
-            echo "No publishConfig found, package.json is ready for npmjs.com."
-          fi
-          cat package.json
-
-      - name: Publish to NPM Registry (npmjs.com)
-        # For scoped packages on npmjs.com, --access=public is needed for the first publish
-        # and if it's intended to be a public package.
+      - name: Publish to NPM Registry
         run: npm publish --access=public
-
-      # --- Publish to GitHub Packages ---
-      - name: Set up Node.js for GitHub Packages
-        uses: actions/setup-node@v4
-        with:
-          node-version: '22' # Redundant if already set, but harmless
-          registry-url: 'https://npm.pkg.github.com'
-          # scope: '@mgks' # Not strictly needed here if package.json name is already @mgks/docmd
-                           # but good for ensuring .npmrc is correctly configured for the @mgks scope.
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Configures .npmrc for GPR
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
-      # The package name is already @mgks/docmd from checkout (and npmjs.com step didn't change it).
-      # No jq transformation of the name is needed.
-      - name: Verify package.json for GitHub Packages
-        run: |
-          echo "package.json for GPR publishing (should be @mgks/docmd):"
-          cat package.json
+      # ----------------------------------------
+      # --- Publish to GitHub Packages (GPR) ---
+      # ----------------------------------------
+      - name: Configure NPM for GitHub Packages registry
+        run: echo "//npm.pkg.github.com/:_authToken=${{ secrets.GITHUB_TOKEN }}" > ~/.npmrc
 
       - name: Publish to GitHub Packages
-        run: npm publish
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/README.md

@@ -28,58 +28,73 @@ Docmd is a Node.js command-line tool for generating fast, beautiful, and lightwe
 -   **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`.
+-   **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.).
 
-## Installation
-**Prerequisites:** [Node.js](https://nodejs.org/) (version 22.x or higher)
+## Installation and Usage
 
-### Quick Start: Your First Site in 60 Seconds
+**Prerequisites:** [Node.js](https://nodejs.org/) (version 22.x or higher) is required.
 
-No global installation is required. You can create and run your site in a new folder with one command.
+### Global Installation (Recommended)
 
-```bash
-# Create a new project in 'my-docs' and navigate into it
-npx @mgks/docmd init my-docs && cd my-docs
-
-# Start the development server
-npm start
-```
-
-Your new documentation site is now running at `http://localhost:3000` *(or, at your selected or available port)*.
-
-### Global Installation
-
-For frequent use, or if you prefer to have the command available system-wide, you can install `docmd` globally using npm.
+This is the recommended approach for developers who will use `docmd` across multiple projects. It makes the `docmd` command available system-wide.
 
+**1. Install Globally:**
 ```bash
 npm install -g @mgks/docmd
 ```
-After installation, you can run the `docmd` commands from any directory.
 
-### Basic Workflow
+**2. Basic Workflow:**
+Once installed, you can use the `docmd` command directly in any project folder.
 
-1.  **Initialize a Project:**
+*   **Initialize a Project:**
     ```bash
+    # This creates docs/, docmd.config.js, and a sample index.md
     docmd init
     ```
-    This creates a `docs/` directory, a `docmd.config.js` file, and a sample `index.md` to get you started.
 
-2.  **Start the Dev Server:**
+*   **Start the Dev Server:**
     ```bash
+    # Starts a live-reloading server at http://localhost:3000
     docmd dev
     ```
-    This starts a live-reloading server to preview your site as you write.
 
-3.  **Build for Production:**
+*   **Build for Production:**
     ```bash
+    # Generates the static site into the `site/` directory
     docmd build
     ```
-    This generates the complete, optimized static site into the `site/` directory, ready for deployment.
+
+### Quick Start (Alternative)
+
+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.
+
+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
+    ```
+
+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
+    ```
+
+Your new documentation site is now running at `http://localhost:3000`.
 
 ## Documentation
 
-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)**.
+For a complete guide, visit the official documentation: **[docmd.mgks.dev](https://docmd.mgks.dev)**.
+
+### 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.
 
 ## Contributing
 

package/config.js

@@ -155,9 +155,21 @@ module.exports = {
           { title: 'Sitemap', path: '/plugins/sitemap', icon: 'map' },
         ],
       },
+      {
+        title: 'Recipes',
+        icon: 'chef-hat',
+        path: '/recipes/',
+        collapsible: true,
+        children: [
+          { title: 'Landing Page', path: '/recipes/landing-page', icon: 'panel-top' },
+          { title: 'Custom Fonts', path: '/recipes/custom-fonts', icon: 'type-outline' },
+          { title: 'Favicon', path: '/recipes/favicon', icon: 'circle-dashed' },
+        ],
+      },
       { title: 'CLI Commands', path: '/cli-commands', icon: 'terminal' },
       { title: 'Deployment', path: '/deployment', icon: 'upload-cloud' },
       { title: 'Contributing', path: '/contributing', icon: 'users-2' },
+      { title: 'Comparison', path: '/comparison', icon: 'shapes' },
 
       { title: 'GitHub', path: 'https://github.com/mgks/docmd', icon: 'github', external: true },
       { title: 'Discussions', path: 'https://github.com/mgks/docmd/discussions', icon: 'message-square', external: true },

package/docs/comparison.md

@@ -0,0 +1,51 @@
+---
+title: "Comparison between docmd, Docusaurus, MkDocs, Mintlify and more"
+description: "A detailed comparison of docmd against Docusaurus, MkDocs, Mintlify, and Docsify."
+---
+
+# Comparing Documentation Tools
+
+Choosing the right tool depends on your specific needs. `docmd` was built to fill the gap between "too simple" (basic parsers) and "too heavy" (full application frameworks).
+
+## Feature Matrix
+
+| Feature | docmd | Docusaurus | MkDocs (Material) | Mintlify | Docsify |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **Core Tech** | Node.js (Native) | React.js | Python | Proprietary | JS (Runtime) |
+| **Output** | Static HTML | React SPA (Hydrated) | Static HTML | Hosted / Next.js | None (Runtime SPA) |
+| **Setup Time** | ~2 minutes | ~15 minutes | ~10 mins (Python env) | Instant (SaaS) | Instant |
+| **Client JS Size** | **Tiny (< 15kb)** | Heavy (React Bundle) | Minimal | Medium | Medium |
+| **Customization** | Standard CSS/JS | React Components | Python/Jinja2 | JSON Config | Vue/Plugins |
+| **SEO** | **Excellent** | Excellent | Excellent | Excellent | **Poor** |
+| **Hosting** | **Anywhere** | Anywhere | Anywhere | **Vendor Locked** | Anywhere |
+| **Cost** | **100% Free OSS** | 100% Free OSS | 100% Free OSS | Freemium | 100% Free OSS |
+
+## Detailed Breakdown
+
+### vs. Docusaurus
+**Docusaurus** is the gold standard for large-scale React projects (like Meta's own docs).
+*   **Choose Docusaurus if:** You need to embed complex React components inside your markdown, need versioning *today*, or are building a massive site with thousands of pages.
+*   **Choose docmd if:** You want a fast, lightweight site that is just HTML/CSS. You don't want to maintain a React dependency tree just to display documentation.
+
+### vs. MkDocs (Material)
+**MkDocs** is widely loved but requires a Python environment.
+*   **Choose MkDocs if:** You are already in the Python ecosystem or need its mature plugin ecosystem immediately.
+*   **Choose docmd if:** You are a JavaScript/Node.js developer. You want to run `npm install` and go, without dealing with `pip`, `requirements.txt`, or Python version conflicts.
+
+### vs. Mintlify
+**Mintlify** is a modern, hosted documentation platform focused on design.
+*   **Choose Mintlify if:** You have a budget and don't want to touch *any* code or configuration. You just want to upload markdown and pay someone to host and style it.
+*   **Choose docmd if:** You want full control over your HTML/CSS and want to host your docs for **free** on GitHub Pages, Vercel, or Netlify without branding watermarks or custom domain fees.
+
+### vs. Docsify
+**Docsify** is a "magical" generator that parses Markdown on the fly in the browser.
+*   **Choose Docsify if:** You absolutely cannot run a build step (e.g., you are hosting on a legacy server that only serves static files and you can't run CI/CD).
+*   **Choose docmd if:** You care about **SEO** and **Performance**. Docsify requires the user's browser to download the Markdown parser and the content before rendering anything, which is bad for search engines and users on slow connections. `docmd` builds real HTML files that load instantly.
+
+## The docmd Philosophy
+
+We believe documentation tools shouldn't be heavy. `docmd` generates **zero-clutter** websites. We don't ship a heavy JavaScript framework to the client just to render text. This results in:
+
+1.  **Better SEO:** Search engines love clean, semantic HTML.
+2.  **Faster Load Times:** No "hydration" delay or runtime parsing.
+3.  **Easier Maintenance:** Standard web technologies (CSS/JS), no framework knowledge required.

package/docs/recipes/custom-fonts.md

@@ -0,0 +1,43 @@
+---
+title: "Recipe: Custom Fonts"
+description: "How to add Google Fonts or custom typefaces to your documentation."
+---
+
+# Adding Custom Fonts
+
+You can easily change the typography of your `docmd` site using CSS variables and a custom stylesheet.
+
+## 1. Select a Font
+Go to [Google Fonts](https://fonts.google.com) and select the font you want (e.g., "Poppins"). Copy the `@import` URL.
+
+## 2. Create a Custom CSS File
+Create a file in your project at `assets/css/typography.css`.
+
+```css
+/* assets/css/typography.css */
+@import url('https://fonts.googleapis.com/css2?family=Poppins:wght@400;600;700&display=swap');
+
+:root {
+  /* Override the default sans-serif font variable */
+  --font-family-sans: 'Poppins', system-ui, -apple-system, sans-serif;
+}
+```
+
+## 3. Register in Config
+Add the file to your `docmd.config.js`:
+
+```javascript
+module.exports = {
+  // ...
+  theme: {
+    name: 'default',
+    customCss: [
+      '/assets/css/typography.css' // Points to your new file
+    ]
+  }
+  // ...
+}
+```
+
+## 4. Restart
+Run `docmd dev`. Your site will now use Poppins!

package/docs/recipes/favicon.md

@@ -0,0 +1,38 @@
+---
+title: "Recipe: Custom Favicon"
+description: "How to add a custom favicon to your documentation site."
+---
+
+# Adding a Custom Favicon
+
+A favicon is the small icon that appears in the browser tab next to your page title. `docmd` makes it easy to add your own.
+
+## 1. Prepare your image
+You can use `.ico`, `.png`, or `.svg` files. For the best compatibility, an `.ico` file is recommended.
+
+## 2. Add to Assets
+Place your image file in your project's assets directory.
+
+```bash
+# Example structure
+my-project/
+  ├── assets/
+  │   └── my-icon.ico  <-- Your file here
+  ├── docs/
+  └── docmd.config.js
+```
+
+## 3. Update Configuration
+Open `docmd.config.js` and update the `favicon` property with the path relative to the output root.
+
+```javascript
+module.exports = {
+  // ...
+  // Points to site/assets/my-icon.ico
+  favicon: '/assets/my-icon.ico', 
+  // ...
+};
+```
+
+## 4. Build
+Run `docmd build` (or `docmd dev`). `docmd` will automatically copy your asset file to the site build and link it in the `<head>` of every page.

package/docs/recipes/index.md

@@ -0,0 +1,12 @@
+---
+title: "Recipes to cook best of docmd"
+description: "Step-by-step guides for common docmd customizations."
+---
+
+# Recipes
+
+Common patterns and "how-to" guides for getting the most out of `docmd`.
+
+*   [**Custom Fonts**](./custom-fonts) - Give your docs a unique personality by loading Google Fonts or local font files.
+*   [**Landing Pages**](./landing-page) - How to create a beautiful, full-width marketing page using the `noStyle` feature.
+*   [**Custom Favicon**](./favicon) - Simple steps to adding your brand's icon.

package/docs/recipes/landing-page.md

@@ -0,0 +1,46 @@
+---
+title: "Recipe: Marketing Landing Page"
+description: "How to build a custom landing page using noStyle."
+---
+
+# Creating a Landing Page
+
+Sometimes you want your `index.html` (the home page) to look completely different from your documentation—like a product marketing page. `docmd` makes this easy with **No-Style Pages**.
+
+## The Concept
+By adding `noStyle: true` to your frontmatter, `docmd` strips away the sidebar, header, and default CSS, giving you a blank canvas while still keeping helpful meta tags.
+
+## Implementation
+
+Create or edit `docs/index.md`:
+
+```html
+---
+title: "My Product"
+description: " The best product ever."
+noStyle: true
+components:
+  meta: true      # Keep SEO tags
+  favicon: true   # Keep favicon
+  scripts: false  # Disable default docmd scripts
+customHead: |
+  <style>
+    body { font-family: sans-serif; margin: 0; }
+    .hero { background: #111; color: #fff; padding: 100px 20px; text-align: center; }
+    .btn { background: #3b82f6; color: white; padding: 10px 20px; text-decoration: none; border-radius: 5px; }
+  </style>
+---
+
+<div class="hero">
+  <h1>Welcome to My Product</h1>
+  <p>The ultimate solution for X, Y, and Z.</p>
+  <br>
+  <a href="/getting-started/" class="btn">Read the Docs →</a>
+</div>
+
+<div class="features">
+   <!-- Your custom HTML features grid here -->
+</div>
+```
+
+This page will be built as `index.html` but will look exactly like your custom HTML, serving as a perfect entry point to your documentation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mgks/docmd",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Generate beautiful, lightweight static documentation sites directly from your Markdown files. Zero clutter, just content.",
   "main": "src/index.js",
   "exports": {