@mgks/docmd 0.2.6 → 0.2.8

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/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/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.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",