@mgks/docmd 0.1.1 → 0.1.3

package/docs/content/no-style-pages.md

@@ -0,0 +1,202 @@
+---
+title: "No-Style Pages"
+description: "Create custom standalone pages with minimal styling and only the components you need."
+---
+
+# No-Style Pages
+
+docmd offers a "no-style" page format that gives you maximum flexibility to create custom standalone pages while still leveraging the docmd infrastructure. This is perfect for creating:
+
+- Landing pages with custom layouts
+- Welcome pages with unique designs
+- Single-page websites
+- Special marketing pages
+- Any page that needs a completely custom design
+
+## How It Works
+
+To create a no-style page, add `noStyle: true` to your page's frontmatter. This tells docmd to use a special template that only includes the components you explicitly request.
+
+By default, a no-style page will render just your content with minimal HTML structure. You can then selectively enable specific components via the `components` object in frontmatter.
+
+## HTML Support
+
+No-style pages fully support raw HTML content without any escaping or processing. You can write pure HTML in your markdown files, and it will be rendered exactly as written. This gives you complete control over the page structure and design.
+
+Unlike regular markdown pages, where HTML might be processed or escaped, no-style pages treat your content as raw HTML, making them perfect for custom layouts and designs.
+
+## Basic Example
+
+Here's a minimal example of a no-style page:
+
+```yaml
+---
+title: "Welcome"
+description: "Welcome to my project"
+noStyle: true
+components:
+  meta: true  # Include meta tags, title, description
+  css: false  # Don't include default CSS
+---
+
+<div style="text-align: center; padding: 50px;">
+  <h1>Welcome to My Project</h1>
+  <p>This is a completely custom page with only the components I need.</p>
+  <a href="/docs/" class="button">View Documentation</a>
+</div>
+```
+
+## Available Components
+
+You can control exactly which components are included in your page by setting them to `true` or `false` in the `components` object:
+
+| Component | Description | Default |
+|-----------|-------------|---------|
+| `meta` | Meta tags, title, description | `true` |
+| `siteTitle` | Include site title after page title | `true` |
+| `favicon` | Include favicon | `true` |
+| `css` | Include main CSS | `false` |
+| `highlight` | Include syntax highlighting CSS | `false` |
+| `theme` | Include theme-specific CSS | `false` |
+| `customCss` | Include custom CSS files from config | `false` |
+| `pluginStyles` | Include plugin-specific CSS | `false` |
+| `pluginHeadScripts` | Include plugin scripts in head | `false` |
+| `layout` | Use main content layout (`true`, `'full'`, or `false`) | `false` |
+| `sidebar` | Include sidebar | `false` |
+| `header` | Include page header | `false` |
+| `pageTitle` | Include page title in header | `false` |
+| `footer` | Include page footer | `false` |
+| `branding` | Include docmd branding in footer | `false` |
+| `logo` | Include logo in sidebar | `false` |
+| `navigation` | Include navigation in sidebar | `false` |
+| `themeToggle` | Include theme toggle button | `false` |
+| `toc` | Include table of contents | `false` |
+| `scripts` | Include all scripts | `false` |
+| `customJs` | Include custom JS files from config | `false` |
+| `pluginBodyScripts` | Include plugin scripts at end of body | `false` |
+
+## Layout Options
+
+The `components.layout` property has three possible values:
+
+- `false` (default): No layout wrapper, just your raw content
+- `true`: Use the main content layout with optional header and footer
+- `'full'`: Same as `true`, a full layout with content area
+
+## Sidebar Option
+
+If you set `components.sidebar: true`, the sidebar will be included with optional logo, navigation, and theme toggle button.
+
+## Custom HTML in Head and Body
+
+You can also include custom HTML in the head and body sections:
+
+```yaml
+---
+title: "Custom Page"
+noStyle: true
+customHead: |
+  <link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;700&display=swap" rel="stylesheet">
+  <style>
+    body { font-family: 'Roboto', sans-serif; }
+  </style>
+customScripts: |
+  <script>
+    document.addEventListener('DOMContentLoaded', () => {
+      console.log('Page loaded!');
+    });
+  </script>
+bodyClass: "landing-page"
+---
+```
+
+## Complete Example
+
+Here's a more complete example of a landing page:
+
+```yaml
+---
+title: "My Project"
+description: "A powerful tool for developers"
+noStyle: true
+components:
+  meta: true
+  favicon: true
+  css: true
+  theme: true
+  layout: true
+  header: true
+  pageTitle: true
+  footer: true
+  branding: true
+  scripts: true
+customHead: |
+  <link href="https://fonts.googleapis.com/css2?family=Poppins:wght@400;600&display=swap" rel="stylesheet">
+  <style>
+    body { font-family: 'Poppins', sans-serif; }
+    .hero { text-align: center; padding: 80px 20px; }
+    .cta-button { display: inline-block; padding: 12px 24px; background: #4a6cf7; color: white; 
+                 text-decoration: none; border-radius: 4px; font-weight: 600; }
+  </style>
+bodyClass: "landing-page"
+---
+
+<div class="hero">
+  <h1>Welcome to My Project</h1>
+  <p>A powerful tool that helps developers build amazing things.</p>
+  <a href="/docs/" class="cta-button">Get Started</a>
+</div>
+
+<div class="features">
+  <div class="feature">
+    <h2>Easy to Use</h2>
+    <p>Simple API and clear documentation make it easy to get started.</p>
+  </div>
+  <div class="feature">
+    <h2>Powerful</h2>
+    <p>Advanced features for when you need them.</p>
+  </div>
+  <div class="feature">
+    <h2>Flexible</h2>
+    <p>Adapt to your workflow, not the other way around.</p>
+  </div>
+</div>
+```
+
+## HTML and Markdown Mixed Content
+
+No-style pages support both HTML and Markdown content. You can freely mix them in your page:
+
+```markdown
+---
+title: "Mixed Content"
+noStyle: true
+components:
+  meta: true
+  css: true
+---
+
+<div style="text-align: center">
+  <h1>My Custom Page</h1>
+</div>
+
+## Regular Markdown Heading
+
+This is regular **Markdown** content that will be processed normally.
+
+<div class="custom-section">
+  <h3>HTML Section</h3>
+  <p>This is HTML content within the page.</p>
+</div>
+
+- Markdown list item 1
+- Markdown list item 2
+```
+
+## Best Practices
+
+1. Start with minimal components and add only what you need
+2. Use the `customHead` property for page-specific styles
+3. Consider creating a separate CSS file for your custom pages
+4. Test your page in both light and dark modes if using theme support
+5. Remember that no-style pages still benefit from docmd's plugins (SEO, analytics, etc.) 

package/docs/index.md

@@ -1,56 +1,143 @@
 ---
-title: "Minimalist Markdown Docs Generator"
-description: "Generate beautiful, lightweight static documentation sites directly from your Markdown files with docmd. Zero clutter, just content."
+title: "docmd: Documentation. Zero Clutter. Just Content."
+description: "A lightweight static documentation site generator that transforms Markdown into beautiful, responsive documentation websites."
+noStyle: true
+components:
+  meta: true
+  favicon: true
+  css: false
+  theme: false
+  scripts: true
+  themeToggle: false
+  lightbox: false
+customHead: |
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=PT+Mono:wght@700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="/assets/css/welcome.css">
+  <script>
+    // Initialize theme from localStorage or system preference
+    function initTheme() {
+      const storedTheme = localStorage.getItem('docmd-theme');
+      if (storedTheme) {
+        document.body.setAttribute('data-theme', storedTheme);
+      } else {
+        const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+        document.body.setAttribute('data-theme', prefersDark ? 'dark' : 'light');
+      }
+    }
+    
+    // Toggle theme between light and dark
+    function toggleTheme() {
+      const currentTheme = document.body.getAttribute('data-theme');
+      const newTheme = currentTheme === 'light' ? 'dark' : 'light';
+      document.body.setAttribute('data-theme', newTheme);
+      localStorage.setItem('docmd-theme', newTheme);
+    }
+    
+    // Run on page load
+    document.addEventListener('DOMContentLoaded', initTheme);
+  </script>
 ---
 
-# docmd
-
-**Generate beautiful, lightweight static documentation sites directly from your Markdown files. Zero clutter, just content.**
-
-`docmd` is a Node.js-based command-line tool that transforms a directory of Markdown files (`.md`) into a clean, fast, and themeable static website. It prioritizes simplicity for the author, leveraging standard Markdown and intuitive configuration, while producing elegant and functional documentation sites.
-
-::: callout tip
-This very documentation site is built using `docmd`!
-:::
-
-## Core Philosophy
-
-*   **Markdown First:** Your content lives in standard `.md` files with simple YAML frontmatter.
-*   **Minimal Configuration:** Sensible defaults with straightforward overrides via `config.js`.
-*   **Lightweight Build:** Fast generation process using Node.js, no complex framework dependencies for the build itself.
-*   **Beautiful Defaults:** Clean, responsive design with light/dark themes and syntax highlighting out-of-the-box.
-*   **Static Output:** Deploy the generated `site/` folder anywhere (GitHub Pages, Netlify, Vercel, etc.).
-
-## Key Features
-
-*   📝 **Standard Markdown & Frontmatter:** Write content naturally, define page metadata (title, description) easily.
-*   🎨 **Themeable:** Built-in light/dark modes, customizable via CSS variables. Uses `highlight.js` for code blocks.
-*   🧩 **Custom Containers:** Add richer components like callouts, cards, and steps using simple `::: name :::` syntax.
-*   ⚙️ **Config-Driven Navigation:** Define your site structure and sidebar navigation in `config.js`. Supports nested items.
-*   🚀 **Fast Static Build:** Node.js script quickly processes files into optimized HTML & CSS.
-*   💻 **Simple CLI:** Easy-to-use commands (`docmd build`, `docmd init`, `docmd dev`) with clear feedback.
-*   🌐 **Deploy Anywhere:** Generates a standard static `site/` directory.
-
-## Get Started Quickly
-
-1.  **Install `docmd`:**
-    ```bash
-    npm install -g @mgks/docmd
-    ```
-2.  **Initialize Your Project:**
-    ```bash
-    cd my-project-docs
-    docmd init
-    ```
-3.  **Write Your Content:**
-    Create `.md` files in the `docs/` directory.
-4.  **Preview Live:**
-    ```bash
-    docmd dev
-    ```
-5.  **Build for Production:**
-    ```bash
-    docmd build
-    ```
-
-Dive into the [Getting Started](/getting-started/installation/) guide for more details, or explore the sidebar to learn about specific features.
+<div class="header-top">
+  <button class="theme-toggle" onclick="toggleTheme()" aria-label="Toggle dark/light mode">
+    <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-sun-moon-icon lucide-sun-moon"><path d="M12 8a2.83 2.83 0 0 0 4 4 4 4 0 1 1-4-4"/><path d="M12 2v2"/><path d="M12 20v2"/><path d="m4.9 4.9 1.4 1.4"/><path d="m17.7 17.7 1.4 1.4"/><path d="M2 12h2"/><path d="M20 12h2"/><path d="m6.3 17.7-1.4 1.4"/><path d="m19.1 4.9-1.4 1.4"/></svg>
+  </button>
+</div>
+
+<div class="landing-container">
+  <div class="content-side">
+    <div class="logo">
+      <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-feather-icon lucide-feather"><path d="M12.67 19a2 2 0 0 0 1.416-.588l6.154-6.172a6 6 0 0 0-8.49-8.49L5.586 9.914A2 2 0 0 0 5 11.328V18a1 1 0 0 0 1 1z"/><path d="M16 8 2 22"/><path d="M17.5 15H9"/></svg>
+      <span class="logo-text">docmd</span>
+    </div>
+
+    <h1>Beautiful Documentation.<br />Zero Clutter. Just Content.</h1>
+
+    <p class="tagline">
+      Transform your Markdown files into elegant, responsive documentation sites with zero setup.
+    </p>
+    
+    <div class="features">
+      <div class="feature">
+        <div class="feature-icon">
+          <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-file-down-icon lucide-file-down"><path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/><path d="M12 18v-6"/><path d="m9 15 3 3 3-3"/></svg>
+        </div>
+        <div class="feature-text">
+          <strong>Markdown Powered</strong>
+          Write in Markdown – get clean HTML
+        </div>
+      </div>
+
+      <div class="feature">
+        <div class="feature-icon">
+          <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-monitor-smartphone-icon lucide-monitor-smartphone"><path d="M18 8V6a2 2 0 0 0-2-2H4a2 2 0 0 0-2 2v7a2 2 0 0 0 2 2h8"/><path d="M10 19v-3.96 3.15"/><path d="M7 19h5"/><rect width="6" height="10" x="16" y="12" rx="2"/></svg>
+        </div>
+        <div class="feature-text">
+          <strong>Responsive Design</strong>
+          Looks great on any device
+        </div>
+      </div>
+
+      <div class="feature">
+        <div class="feature-icon">
+          <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-sun-icon lucide-sun"><circle cx="12" cy="12" r="4"/><path d="M12 2v2"/><path d="M12 20v2"/><path d="m4.93 4.93 1.41 1.41"/><path d="m17.66 17.66 1.41 1.41"/><path d="M2 12h2"/><path d="M20 12h2"/><path d="m6.34 17.66-1.41 1.41"/><path d="m19.07 4.93-1.41 1.41"/></svg>
+        </div>
+        <div class="feature-text">
+          <strong>Light & Dark Modes</strong>
+          Themes with auto dark mode
+        </div>
+      </div>
+
+      <div class="feature">
+        <div class="feature-icon">
+          <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 20h9"></path><path d="M16.5 3.5a2.121 2.121 0 0 1 3 3L7 19l-4 1 1-4L16.5 3.5z"></path></svg>
+        </div>
+        <div class="feature-text">
+          <strong>Highly Customizable</strong>
+          Extend with plugins & containers
+        </div>
+      </div>
+    </div>
+
+    <a href="https://www.producthunt.com/posts/docmd?embed=true&amp;utm_source=badge-featured&amp;utm_medium=badge&amp;utm_souce=badge-docmd" target="_blank" style="margin-bottom: .5em;"><img src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=963681&amp;theme=dark&amp;t=1747100482899" alt="docmd - Generate beautiful, light documentation sites from Markdown. | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54"></a>
+
+    <div class="buttons">
+      <a href="/getting-started/" class="btn btn-primary">
+        <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-rocket-icon lucide-rocket"><path d="M4.5 16.5c-1.5 1.26-2 5-2 5s3.74-.5 5-2c.71-.84.7-2.13-.09-2.91a2.18 2.18 0 0 0-2.91-.09z"/><path d="m12 15-3-3a22 22 0 0 1 2-3.95A12.88 12.88 0 0 1 22 2c0 2.72-.78 7.5-6 11a22.35 22.35 0 0 1-4 2z"/><path d="M9 12H4s.55-3.03 2-4c1.62-1.08 5 0 5 0"/><path d="M12 15v5s3.03-.55 4-2c1.08-1.62 0-5 0-5"/></svg>
+        Get Started
+      </a>
+      <a href="https://github.com/mgks/docmd" target="_blank" rel="noopener" class="btn btn-secondary">
+        <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15 22v-4a4.8 4.8 0 0 0-1-3.5c3 0 6-2 6-5.5.08-1.25-.27-2.48-1-3.5.28-1.15.28-2.35 0-3.5 0 0-1 0-3 1.5-2.64-.5-5.36-.5-8 0C6 2 5 2 5 2c-.3 1.15-.3 2.35 0 3.5A5.403 5.403 0 0 0 4 9c0 3.5 3 5.5 6 5.5-.39.49-.68 1.05-.85 1.65-.17.6-.22 1.23-.15 1.85v4"></path><path d="M9 18c-4.51 2-5-2-7-2"></path></svg>
+        GitHub
+      </a>
+    </div>
+
+    <div class="social-links">
+      <a href="https://github.com/sponsors/mgks" target="_blank" rel="noopener" class="social-link" title="Buy me a Coffee – GitHub Sponsors">
+        <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-heart-handshake-icon lucide-heart-handshake"><path d="M19 14c1.49-1.46 3-3.21 3-5.5A5.5 5.5 0 0 0 16.5 3c-1.76 0-3 .5-4.5 2-1.5-1.5-2.74-2-4.5-2A5.5 5.5 0 0 0 2 8.5c0 2.3 1.5 4.05 3 5.5l7 7Z"/><path d="M12 5 9.04 7.96a2.17 2.17 0 0 0 0 3.08c.82.82 2.13.85 3 .07l2.07-1.9a2.82 2.82 0 0 1 3.79 0l2.96 2.66"/><path d="m18 15-2-2"/><path d="m15 18-2-2"/></svg>
+      </a>
+      <!--<a href="https://twitter.com/share?url=https://docmd.mgks.dev" target="_blank" rel="noopener" class="social-link">
+        <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M22 4s-.7 2.1-2 3.4c1.6 10-9.4 17.3-18 11.6 2.2.1 4.4-.6 6-2C3 15.5.5 9.6 3 5c2.2 2.6 5.6 4.1 9 4.5-.9-4.2 4-6.6 7-3.8 1.1 0 3-1.2 3-1.2z"></path></svg>
+      </a>-->
+    </div>
+  </div>
+  
+  <div class="preview-side">
+    <div class="preview-stack">
+      <div class="preview-image top">
+        <img src="/assets/images/preview-light-1.png" alt="docmd documentation preview" class="light-img">
+        <img src="/assets/images/preview-dark-1.png" alt="docmd documentation preview" class="dark-img">
+      </div>
+      <div class="preview-image middle">
+        <img src="/assets/images/preview-light-2.png" alt="docmd documentation preview" class="light-img">
+        <img src="/assets/images/preview-dark-2.png" alt="docmd documentation preview" class="dark-img">
+      </div>
+      <div class="preview-image bottom">
+        <img src="/assets/images/preview-light-3.png" alt="docmd documentation preview" class="light-img">
+        <img src="/assets/images/preview-dark-3.png" alt="docmd documentation preview" class="dark-img">
+      </div>
+    </div>
+  </div>
+</div> 

package/docs/overview.md

@@ -0,0 +1,56 @@
+---
+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.**
+
+`docmd` is a Node.js-based command-line tool that transforms a directory of Markdown files (`.md`) into a clean, fast, and themeable static website. It prioritizes simplicity for the author, leveraging standard Markdown and intuitive configuration, while producing elegant and functional documentation sites.
+
+::: callout tip
+This very documentation site is built using `docmd`!
+:::
+
+## Core Philosophy
+
+*   **Markdown First:** Your content lives in standard `.md` files with simple YAML frontmatter.
+*   **Minimal Configuration:** Sensible defaults with straightforward overrides via `config.js`.
+*   **Lightweight Build:** Fast generation process using Node.js, no complex framework dependencies for the build itself.
+*   **Beautiful Defaults:** Clean, responsive design with light/dark themes and syntax highlighting out-of-the-box.
+*   **Static Output:** Deploy the generated `site/` folder anywhere (GitHub Pages, Netlify, Vercel, etc.).
+
+## Key Features
+
+*   📝 **Standard Markdown & Frontmatter:** Write content naturally, define page metadata (title, description) easily.
+*   🎨 **Themeable:** Built-in light/dark modes, customizable via CSS variables. Uses `highlight.js` for code blocks.
+*   🧩 **Custom Containers:** Add richer components like callouts, cards, and steps using simple `::: name :::` syntax.
+*   ⚙️ **Config-Driven Navigation:** Define your site structure and sidebar navigation in `config.js`. Supports nested items.
+*   🚀 **Fast Static Build:** Node.js script quickly processes files into optimized HTML & CSS.
+*   💻 **Simple CLI:** Easy-to-use commands (`docmd build`, `docmd init`, `docmd dev`) with clear feedback.
+*   🌐 **Deploy Anywhere:** Generates a standard static `site/` directory.
+
+## Get Started Quickly
+
+1.  **Install `docmd`:**
+    ```bash
+    npm install -g @mgks/docmd
+    ```
+2.  **Initialize Your Project:**
+    ```bash
+    cd my-project-docs
+    docmd init
+    ```
+3.  **Write Your Content:**
+    Create `.md` files in the `docs/` directory.
+4.  **Preview Live:**
+    ```bash
+    docmd dev
+    ```
+5.  **Build for Production:**
+    ```bash
+    docmd build
+    ```
+
+Dive into the [Getting Started](/getting-started/installation/) guide for more details, or explore the sidebar to learn about specific features.

package/docs/theming/assets-management.md

@@ -0,0 +1,126 @@
+---
+title: "Assets Management"
+description: "Learn how to manage and customize your assets (CSS, JavaScript, images) in your docmd site."
+---
+
+# Assets Management
+
+Managing your custom assets (CSS, JavaScript, images) is an important part of customizing your documentation site. `docmd` provides flexible ways to include and manage these assets.
+
+## Project Structure
+
+When you initialize a new project with `docmd init`, it creates the following structure:
+
+```
+your-project/
+├── assets/           # User assets directory
+│   ├── css/          # Custom CSS files
+│   ├── js/           # Custom JavaScript files
+│   └── images/       # Custom images
+├── docs/             # Markdown content
+├── config.js
+└── ...
+```
+
+This structure makes it easy to organize and manage your custom assets.
+
+## How Assets Are Handled
+
+There are two main ways to manage assets in your docmd site:
+
+### 1. Root-Level Assets Directory (Recommended)
+
+The simplest and recommended approach is to use the `assets/` directory in your project root:
+
+**How it works:**
+- During the build process, docmd automatically copies everything from your root `assets/` directory to the output `site/assets/` directory
+- Your custom assets take precedence over docmd's built-in assets with the same name
+- This approach is ideal for GitHub Pages deployments and other hosting scenarios
+
+**Example workflow:**
+1. Create or modify files in your project's `assets/` directory:
+   ```
+   assets/css/custom-styles.css
+   assets/js/interactive-features.js
+   assets/images/logo.png
+   ```
+
+2. Reference these files in your `config.js`:
+   ```javascript
+   module.exports = {
+     // ...
+     theme: {
+       // ...
+       customCss: [
+         '/assets/css/custom-styles.css',
+       ],
+     },
+     customJs: [
+       '/assets/js/interactive-features.js',
+     ],
+     // ...
+   };
+   ```
+
+3. Use images in your Markdown content:
+   ```markdown
+   ![Logo](/assets/images/logo.png)
+   ```
+
+4. Build your site:
+   ```bash
+   docmd build
+   ```
+
+### 2. Customizing Default Assets
+
+If you want to modify docmd's default assets:
+
+1. First, build your site normally to generate all assets:
+   ```bash
+   docmd build
+   ```
+
+2. Modify the generated files in the `site/assets` directory as needed.
+
+3. When rebuilding, use the `--preserve` flag to keep your customized files:
+   ```bash
+   docmd build --preserve
+   ```
+
+4. If you want to update to the latest docmd assets (for example, after updating the package), run without the preserve flag:
+   ```bash
+   docmd build
+   ```
+
+This approach allows you to:
+- Get the latest assets by default when you update the package
+- Preserve your customizations when needed with `--preserve`
+- See which files are being preserved during the build process
+
+The preservation behavior works with both `build` and `dev` commands:
+```bash
+# Preserve custom assets during development
+docmd dev --preserve
+```
+
+## Asset Precedence
+
+When multiple assets with the same name exist, docmd follows this precedence order:
+
+1. **User assets** from the root `assets/` directory (highest priority)
+2. **Preserved assets** from previous builds (if `--preserve` is enabled, which is the default)
+3. **Built-in assets** from the docmd package (lowest priority)
+
+This ensures your custom assets always take precedence over default ones.
+
+## GitHub Pages Deployment
+
+When deploying to GitHub Pages, your assets structure is preserved. If you're using a custom domain or GitHub Pages URL, make sure your asset paths are correctly configured.
+
+For more information on deployment, see the [Deployment](/deployment/) documentation.
+
+## Related Topics
+
+- [Custom CSS & JS](/theming/custom-css-js/) - Learn how to configure custom CSS and JavaScript
+- [Theming](/theming/) - Explore other theming options for your documentation site 

package/docs/theming/custom-css-js.md

@@ -1,5 +1,5 @@
 ---
-title: "Custom CSS & JS"
+title: "Custom Styles & Scripts"
 description: "Learn how to add your own custom CSS and JavaScript to your docmd site for advanced customization."
 ---
 
@@ -30,41 +30,8 @@ module.exports = {
 **How it works:**
 *   Each string in the `customCss` array should be an absolute path from the root of your generated `site/` directory (e.g., if your file is `site/assets/css/my-branding.css`, the path is `/assets/css/my-branding.css`).
 *   These `<link rel="stylesheet">` tags will be added to the `<head>` of every page *after* the main theme CSS and `highlight.js` CSS. This allows your custom styles to override the default theme styles.
-*   You are responsible for ensuring these CSS files exist at the specified locations in your final `site/` output. Typically, you would:
-    1.  Create your custom CSS files (e.g., `my-branding.css`).
-    2.  Place them in a folder within your project (e.g., `my-project/static-assets/css/`).
-    3.  Ensure that this folder (or its contents) is copied to the correct location in your `site/` directory during `docmd`'s asset copying process. If `docmd` copies a top-level `assets/` folder from your source, place them there.
 
-## Managing Custom Assets
-
-By default, `docmd` will always update assets to the latest version when you run `build` or `dev` commands. This ensures your site benefits from the latest improvements and fixes.
-
-### Customizing Default Assets
-
-If you want to customize default assets (like theme CSS files or scripts):
-
-1. First, build your site normally to generate all assets:
-   ```bash
-   docmd build
-   ```
-
-2. Modify the generated files in the `site/assets` directory as needed.
-
-3. When rebuilding, use the `--preserve` flag to keep your customized files:
-   ```bash
-   docmd build --preserve
-   ```
-
-This approach allows you to:
-- Always get the latest assets when you want them (default behavior)
-- Preserve your customizations when needed (with `--preserve`)
-- Easily see which files are being preserved during the build process
-
-The `--preserve` flag works with both `build` and `dev` commands:
-```bash
-# Preserve custom assets during development
-docmd dev --preserve
-```
+> **Note:** For information on how to manage your custom asset files (CSS, JS, images), see the [Assets Management](/theming/assets-management/) documentation.
 
 **Use Cases for Custom CSS:**
 *   **Overriding CSS Variables:** The `default` theme uses CSS variables extensively. You can redefine these in your custom CSS.
@@ -104,7 +71,6 @@ module.exports = {
 **How it works:**
 *   Each string in the `customJs` array should be an absolute path from the root of your generated `site/` directory.
 *   These `<script src="..."></script>` tags will be added just before the closing `</body>` tag on every page. This ensures the DOM is loaded before your scripts run and is generally better for page performance.
-*   Similar to custom CSS, you are responsible for ensuring these JavaScript files exist at the specified locations in your final `site/` output.
 
 **Use Cases for Custom JS:**
 *   Adding interactive elements (e.g., custom modals, tabs not provided by `docmd`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mgks/docmd",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Generate beautiful, lightweight static documentation sites directly from your Markdown files. Zero clutter, just content.",
   "main": "src/index.js",
   "bin": {
@@ -35,7 +35,6 @@
   },
   "homepage": "https://github.com/mgks/docmd#readme",
   "dependencies": {
-    "@mgks/docmd": "^0.1.0",
     "chokidar": "^3.6.0",
     "commander": "^12.0.0",
     "ejs": "^3.1.9",