@mgks/docmd 0.1.3 → 0.1.4

package/.github/workflows/deploy-docmd.yml

@@ -23,11 +23,11 @@ jobs:
       - name: Set up Node.js ⚙️
         uses: actions/setup-node@v4
         with:
-          node-version: '22' # Use Node.js 22
+          node-version: '22'
           cache: 'npm'
 
       - name: Install Dependencies 📦
-        run: npm ci # Use ci for cleaner installs in CI
+        run: npm ci
 
       - name: Build docmd's Own Docs 🛠️
         run: node ./bin/docmd.js build

package/assets/css/welcome.css

@@ -335,6 +335,9 @@
     :root {
       --container-padding: 1.5rem;
     }
+    body {
+      overflow: auto;
+    }
     
     .content-side {
       padding: 2rem 0;
@@ -353,7 +356,20 @@
     }
     
     .header-top {
-      right: 1.5rem;
+      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 {

package/config.js

@@ -31,7 +31,7 @@ module.exports = {
 
   // Custom JavaScript Files
   customJs: [               // Array of paths to custom JS files, loaded at end of body
-    // '/assets/js/docmd-image-lightbox.js', // Image lightbox functionality (commented out)
+     '/assets/js/docmd-image-lightbox.js', // Image lightbox functionality
   ],
 
   // Plugins Configuration (Object format)
@@ -127,7 +127,9 @@ module.exports = {
       { title: 'Deployment', path: '/deployment', icon: 'upload-cloud' },
       { title: 'Contributing', path: '/contributing', icon: 'users-2' },
 
-      { title: 'GitHub', path: 'https://github.com/mgks/docmd', icon: 'github', external: true }
+      { 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 },
+      { title: 'Issues', path: 'https://github.com/mgks/docmd/issues', icon: 'badge-alert', external: true }
   ],
 
   // Footer Configuration

package/docs/cli-commands.md

@@ -85,8 +85,7 @@ This provides a fast feedback loop, allowing you to see your changes almost inst
     *   **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`
 
-*   `-p, --port <port_number>` (Future Option)
-    *   **Description:** While not yet implemented, a future version might allow specifying a custom port for the development server. Currently, it defaults to port 3000 or the next available port if 3000 is in use.
+**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.
 
 ## Global Options (Apply to all commands)
 

package/docs/configuration.md

@@ -24,7 +24,7 @@ module.exports = {
   outputDir: 'site',
 
   theme: {
-    name: 'default',        // Name of the built-in theme to use (e.g., 'default', 'classic')
+    name: 'sky',            // Name of the built-in theme to use (e.g., 'sky', 'default')
     defaultMode: 'light',   // 'light' or 'dark'
     enableModeToggle: true, // Show UI button to toggle light/dark modes
     customCss: [            // Array of paths to your custom CSS files
@@ -37,20 +37,32 @@ module.exports = {
     // '/js/extra-functionality.js', // Loaded at the end of the body
   ],
 
-  plugins: [
-    // Example: Enable built-in SEO enhancements
-    // ['seo', {
-    //   defaultDescription: 'A fantastic site about interesting things.',
-    //   openGraph: { defaultImage: '/assets/images/og-social-default.png' },
-    //   twitter: { cardType: 'summary_large_image', siteUsername: '@MyProject' }
-    // }],
-
-    // Example: Enable Google Analytics (Universal Analytics)
-    // ['analytics-google-ua', { trackingId: 'UA-XXXXXXXXX-Y' }],
+  plugins: {
+    // SEO Plugin Configuration
+    seo: {
+      defaultDescription: 'A fantastic site about interesting things.',
+      openGraph: { 
+        defaultImage: '/assets/images/og-social-default.png'
+      },
+      twitter: { 
+        cardType: 'summary_large_image', 
+        siteUsername: '@MyProject' 
+      }
+    },
 
-    // Example: Enable Google Analytics 4
-    // ['analytics-google-v4', { measurementId: 'G-XXXXXXXXXX' }],
-  ],
+    // Google Analytics 4
+    analytics: {
+      googleV4: { 
+        measurementId: 'G-XXXXXXXXXX' 
+      }
+    },
+    
+    // Sitemap generation
+    sitemap: {
+      defaultChangefreq: 'weekly',
+      defaultPriority: 0.8
+    }
+  },
 
   navigation: [
     { title: 'Home', path: '/', icon: 'home' }, // Icon names correspond to SVGs
@@ -137,15 +149,15 @@ Configures the visual theme of your site.
 *   **Paths:** Should be relative to the `outputDir` root (e.g., `'/js/my-analytics-alternative.js'`).
 *   **Example:** `customJs: ['/assets/js/interactive-component.js']`
 
-## `plugins` (Array)
-*   **Type:** `Array`
-*   **Default:** `[]`
-*   **Description:** An array to configure and enable plugins. `docmd` will ship with some core "local" plugins (like SEO and Analytics) that you can enable here. Future versions might support third-party plugins.
-*   **Format:** Each item in the array is typically another array: `['plugin-name', { pluginOptions }]` or a direct `require()` for local project plugins (advanced usage).
+## `plugins` (Object)
+*   **Type:** `Object`
+*   **Default:** `{}`
+*   **Description:** An object to configure and enable plugins. `docmd` ships with core plugins like SEO, Analytics, and Sitemap that you can configure here.
+*   **Format:** Each key in the object represents a plugin name, and its value is an object containing the plugin's configuration options.
 *   **Built-in Plugin Examples:**
-    *   `['seo', { defaultDescription: '...', openGraph: { ... }, ... }]`
-    *   `['analytics-google-ua', { trackingId: 'UA-...' }]`
-    *   `['analytics-google-v4', { measurementId: 'G-...' }]`
+    *   `seo: { defaultDescription: '...', openGraph: { ... }, ... }`
+    *   `analytics: { googleV4: { measurementId: 'G-XXXXXXXXXX' } }`
+    *   `sitemap: { defaultChangefreq: 'weekly', defaultPriority: 0.8 }`
 *   **See Also:** [Plugins](/plugins/)
 
 ## `navigation` (Array of Objects)

package/docs/content/frontmatter.md

@@ -26,7 +26,7 @@ tags:
 *   **`title`** (String, Required)
     *   **Purpose:** This is the primary title of the page.
     *   **Usage:**
-        *   Used for the HTML `<title>` tag (e.g., `Page Title | Site Title`).
+        *   Used for the HTML `<title>` tag (e.g., `Page Title : Site Title`).
         *   Often used as the main heading (`<h1>`) on the page by default (though themes can customize this).
         *   Used as the display text for links in the navigation sidebar if the path matches.
     *   **Example:** `title: "Installation Guide"`
@@ -68,7 +68,7 @@ This guide will walk you through installing our application...
 ```
 
 In this example:
-*   The browser tab will show "Installation Steps | Your Site Title".
+*   The browser tab will show "Installation Steps : Your Site Title".
 *   The `<meta name="description">` will be set.
 *   The `order: 1` field is available if you later want to sort "guides" pages by this value.
 

package/docs/content/index.md

@@ -9,9 +9,10 @@ docmd uses Markdown files to create beautiful documentation. This section covers
 
 ## Available Guides
 
-- [**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
-- [**Custom Containers**](/content/custom-containers) - Special content blocks like callouts and cards
+- [**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
+- [**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
 
 Choose a topic from the sidebar to get started.

package/docs/content/markdown-syntax.md

@@ -51,7 +51,7 @@ You can use all standard Markdown elements:
     ```markdown
     [Link Text](https://www.example.com)
     [Link with Title](https://www.example.com "Link Title")
-    [Relative Link to another page](../section/other-page.md)
+    [Relative Link to another page](../section/other-page/)
     ```
     *Note: For internal links to other documentation pages, use relative paths to the `.md` files. `docmd` will convert these to the correct HTML paths during the build.*
 
@@ -152,7 +152,7 @@ Because `markdown-it` is configured with `html: true`, you can embed raw HTML di
 </div>
 ```
 
-For most formatting needs, standard Markdown and `docmd`'s [Custom Containers](./custom-containers.md) should suffice.
+For most formatting needs, standard Markdown and `docmd`'s [Custom Containers](/content/custom-containers/) should suffice.
 
 # Advanced Markdown Capabilities
 
@@ -264,7 +264,7 @@ $$
 ## Container Extensions
 
 Beyond standard Markdown, docmd provides custom containers for enhanced formatting. 
-These are detailed in the [Custom Containers](./custom-containers.md) guide, and include:
+These are detailed in the [Custom Containers](/content/custom-containers/) guide, and include:
 
 ::: callout info
 Use containers for callouts, cards, and steps to structure your documentation.
@@ -274,4 +274,4 @@ Use containers for callouts, cards, and steps to structure your documentation.
 
 Markdown provides a powerful yet simple way to write and format documentation. With docmd's extensions and customizations, you can create rich, beautiful documentation that's easy to maintain.
 
-For more examples and practical applications, check the rest of the documentation or browse the source of this page by viewing its Markdown file.
+For more examples and practical applications, check the rest of the documentation or browse the source of this page by viewing its Markdown file.

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

@@ -105,6 +105,6 @@ bodyClass: "no-style-example"
       without affecting the rest of your site.
     </p>
     
-    <a href="/content/no-style-pages" class="button">Get Back to No-Style Pages Documentation</a>
+    <a href="/content/no-style-pages/" class="button">Get Back to No-Style Pages Documentation</a>
   </div>
 </div> 

package/docs/contributing.md

@@ -58,6 +58,13 @@ To set up `docmd` for local development:
    * Follow the existing code style and formatting.
    * Consider running `npm run lint` to check for style issues (if set up).
 
+### Environment Setup
+
+To enable live change tracking for internal files during development, set the DOCMD_DEV environment variable:
+
+- **Temporarily:** Run `export DOCMD_DEV=true` in your terminal before starting the dev server.
+- **Permanently:** Add `export DOCMD_DEV=true` to your `~/.zshrc` file and run `source ~/.zshrc`.
+
 ## Pull Request Process
 
 Once you're satisfied with your changes:

package/docs/deployment.md

@@ -59,14 +59,12 @@ The most robust and automated way to deploy to GitHub Pages is using a GitHub Ac
 Create a file at `.github/workflows/deploy-docs.yml` with the following content:
 
 ```yaml
-name: Deploy docmd docs to Pages
+name: Deploy docmd docs to GitHub Pages
 
 on:
-  # Run on pushes to main branch
   push:
-    branches: ["main"]
-  # Allows manual workflow trigger from Actions tab
-  workflow_dispatch:
+    branches: ["main"]  # Your default branch
+  workflow_dispatch:   # Allows manual workflow trigger from Actions tab
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
@@ -74,46 +72,39 @@ permissions:
   pages: write
   id-token: write
 
-# Allow only one concurrent deployment
-concurrency:
-  group: "pages"
-  cancel-in-progress: false
-
 jobs:
-  build:
+  build-and-deploy:
     runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
         with:
-          node-version: '20' # Or the Node.js version docmd supports/requires
+          node-version: '22'
           cache: 'npm'
+
       - name: Install docmd (globally or from devDependencies)
-        # If docmd is a dev dependency of the project being documented:
-        # run: npm ci && npm run build:docs # Assuming 'build:docs' script runs 'docmd build'
-        # If installing docmd globally for this action:
-        run: npm install -g docmd # Or your scoped package name e.g. @mgks/docmd
+        run: npm install -g @mgks/docmd
+
       - name: Build site with docmd
         run: docmd build # Assumes config.js is in the root and correctly points to srcDir/outputDir
+
       - name: Setup Pages
-        uses: actions/configure-pages@v3
+        uses: actions/configure-pages@v5
+
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v2
+        uses: actions/upload-pages-artifact@v3
         with:
-          # This should be your outputDir path
-          path: './site' # or './docs' if you set outputDir: 'docs'
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
+          path: ./site # This should be your outputDir path
+
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v2
+        uses: actions/deploy-pages@v4
 ```
 
 Then:

package/docs/getting-started/basic-usage.md

@@ -36,6 +36,7 @@ Create your Markdown (`.md`) files inside the `docs/` directory. You can organiz
 
 ```
 my-awesome-docs/
+├── assets/
 ├── docs/
 │   ├── index.md
 │   └── api/
@@ -47,7 +48,7 @@ my-awesome-docs/
 └── config.js
 ```
 
-Each Markdown file should start with YAML frontmatter to define metadata like the page title. See [Writing Content > Frontmatter](/writing-content/frontmatter/) for details.
+Each Markdown file should start with YAML frontmatter to define metadata like the page title. See [Content > Frontmatter](/content/frontmatter/) for details.
 
 ## 3. Preview Your Site (`docmd dev`)
 
@@ -85,4 +86,4 @@ This command:
 
 The contents of the `site/` directory are all you need to deploy your documentation. You can upload this folder to any static web hosting provider. See [Deployment](/deployment/) for more information.
 
-This covers the fundamental workflow of using `docmd`. Next, you'll want to learn more about [Writing Content](/writing-content/) and [Configuration](/configuration/).
+This covers the fundamental workflow of using `docmd`. Next, you'll want to learn more about [Content](/content/) and [Configuration](/configuration/).

package/docs/getting-started/index.md

@@ -11,11 +11,11 @@ Whether you're documenting a new open-source project, an internal tool, or just
 
 ## What You'll Learn:
 
-*   **[Installation](./installation.md):** How to install `docmd` on your system using npm.
-*   **[Basic Usage](./basic-usage.md):**
+*   **[Installation](/getting-started/installation/):** How to install `docmd` on your system using npm.
+*   **[Basic Usage](/getting-started/basic-usage/):**
     *   Initializing a new `docmd` project with `docmd init`.
     *   Adding and structuring your Markdown content.
     *   Building your static site with `docmd build`.
     *   Previewing your site with live reloading using `docmd dev`.
 
-Ready to begin? Let's start with [Installation](./installation.md).
+Ready to begin? Let's start with [Installation](/getting-started/installation/).

package/docs/getting-started/installation.md

@@ -5,7 +5,7 @@ description: "Learn how to install docmd on your system globally or as a project
 
 # Installation
 
-You can install `docmd` using npm (Node Package Manager), which comes with Node.js. If you don't have Node.js and npm installed, please visit [nodejs.org](https://nodejs.org/) to download and install them first (Node.js version 20.x or higher is recommended for `docmd`).
+You can install `docmd` using npm (Node Package Manager), which comes with Node.js. If you don't have Node.js and npm installed, please visit [nodejs.org](https://nodejs.org/) to download and install them first (Node.js version 22.x or higher is required for `docmd`).
 
 ## Global Installation (Recommended for CLI Use)
 

package/docs/index.md

@@ -1,5 +1,5 @@
 ---
-title: "docmd: Documentation. Zero Clutter. Just Content."
+title: "Documentation. Zero Clutter. Just Content."
 description: "A lightweight static documentation site generator that transforms Markdown into beautiful, responsive documentation websites."
 noStyle: true
 components:
@@ -7,10 +7,9 @@ components:
   favicon: true
   css: false
   theme: false
-  scripts: true
-  themeToggle: false
-  lightbox: false
+  scripts: false
 customHead: |
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <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">
@@ -26,7 +25,7 @@ customHead: |
         document.body.setAttribute('data-theme', prefersDark ? 'dark' : 'light');
       }
     }
-    
+
     // Toggle theme between light and dark
     function toggleTheme() {
       const currentTheme = document.body.getAttribute('data-theme');
@@ -34,7 +33,7 @@ customHead: |
       document.body.setAttribute('data-theme', newTheme);
       localStorage.setItem('docmd-theme', newTheme);
     }
-    
+
     // Run on page load
     document.addEventListener('DOMContentLoaded', initTheme);
   </script>
@@ -101,8 +100,6 @@ customHead: |
       </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>
@@ -118,9 +115,9 @@ customHead: |
       <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">
+      <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>-->
+      </a>
     </div>
   </div>
   
@@ -140,4 +137,4 @@ customHead: |
       </div>
     </div>
   </div>
-</div> 
+</div>

package/docs/plugins/sitemap.md

@@ -85,4 +85,4 @@ sitemap: false
 
 ## Verifying Your Sitemap
 
-After building your site, check the generated sitemap at `your-site/sitemap.xml`. You can also submit the sitemap URL to search engines like Google Search Console or Bing Webmaster Tools to help them discover and index your content more efficiently. 
+After building your site, check the generated sitemap at `your-site/sitemap.xml`. You can also submit the sitemap URL to search engines like Google Search Console or Bing Webmaster Tools to help them discover and index your content more efficiently.

package/docs/theming/assets-management.md

@@ -123,4 +123,4 @@ For more information on deployment, see the [Deployment](/deployment/) documenta
 ## 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 
+- [Theming](/theming/) - Explore other theming options for your documentation site

package/docs/theming/available-themes.md

@@ -7,79 +7,57 @@ description: "An overview of the built-in themes provided by docmd."
 
 `docmd` allows you to choose from a selection of built-in themes to quickly change the overall look and feel of your documentation site. You can specify the theme in your `config.js` file using the `theme.name` property.
 
-## 1. `default` Theme
-
-*   **`theme.name: 'default'`** (This is the default if `theme.name` is not specified)
-*   **Description:** The standard `docmd` theme. It's designed to be clean, modern, responsive, and highly readable. It features:
-    *   A collapsible sidebar for navigation.
-    *   Support for light and dark color modes.
-    *   Clear typography optimized for documentation.
-    *   Well-styled custom containers (callouts, cards, steps).
-    *   Effective syntax highlighting for code blocks.
-*   **When to use:** A great general-purpose theme suitable for most documentation projects.
-
 ```javascript
 // config.js
 module.exports = {
   // ...
   theme: {
-    name: 'default',
-    defaultMode: 'light',
+    name: 'theme-name', // Options: 'default', 'sky', 'ruby'
+    defaultMode: 'light', // or 'dark'
     // ...
   },
   // ...
 };
 ```
 
+## 1. `default` Theme
+
+*   **`theme.name: 'default'`**
+*   **Description:** The foundation of all docmd themes. This is not a separate theme but the base styling that's always included regardless of which theme you select. It provides:
+    *   Basic layout structure with sidebar and content area
+    *   Essential typography and spacing
+    *   Core styling for documentation elements like code blocks, tables, and custom containers
+    *   Light and dark mode foundation
+*   **When to use:** When you want a minimalist, clean interface without additional styling layers. This is the most lightweight option.
+
 ## 2. `sky` Theme
 
-*   **`theme.name: 'sky'`**
+*   **`theme.name: 'sky'`** (This is the default if `theme.name` is not specified)
 *   **Description:** A modern theme inspired by popular documentation platforms, with a fresh and airy design. It features:
-    *   A clean, minimalist interface with subtle shadows and rounded corners.
-    *   Custom typography with improved readability.
-    *   Refined color palette for both light and dark modes.
-    *   Enhanced callout and container styles.
-    *   Premium documentation feel with careful attention to spacing and contrast.
+    *   A clean, minimalist interface with subtle shadows and rounded corners
+    *   Custom typography with improved readability
+    *   Refined color palette for both light and dark modes
+    *   Enhanced callout and container styles
+    *   Premium documentation feel with careful attention to spacing and contrast
 *   **When to use:** When you want a premium, polished look for your documentation site.
 
-```javascript
-// config.js
-module.exports = {
-  // ...
-  theme: {
-    name: 'sky',
-    defaultMode: 'light', // or 'dark'
-    // ...
-  },
-  // ...
-};
-```
-
-## Light and Dark Mode
-
-All themes support both light and dark color modes. You can set the default mode using the `theme.defaultMode` property and enable a toggle button with `theme.enableModeToggle`:
-
-```javascript
-// config.js
-module.exports = {
-  // ...
-  theme: {
-    name: 'sky', // or 'default'
-    defaultMode: 'dark', // Start in dark mode
-    enableModeToggle: true, // Show a toggle button in the sidebar
-    // ...
-  },
-  // ...
-};
-```
+## 3. `ruby` Theme
 
-Users can switch between modes using the toggle button in the sidebar, and their preference will be saved in localStorage for future visits.
+*   **`theme.name: 'ruby'`**
+*   **Description:** An elegant, vibrant theme inspired by the precious gemstone. It features:
+    *   Rich, jewel-toned color palette centered around ruby reds and complementary colors
+    *   Sophisticated typography with serif headings and sans-serif body text
+    *   Distinctive card and callout designs with gem-like faceted styling
+    *   Subtle gradients and depth effects that evoke the brilliance of gemstones
+    *   Luxurious dark mode with deep, rich backgrounds and vibrant accent colors
+*   **When to use:** When you want your documentation to have a distinctive, premium feel with rich colors and elegant typography.
 
 ## How Themes Work
 
 Each theme consists of CSS files located within `docmd`'s internal assets. When you select a theme name, `docmd` links the corresponding stylesheet in your site's HTML:
 
 - `default` theme uses the base CSS with no additional theme stylesheet
-- `sky` theme loads `theme-sky.css` with its custom styling
+- `sky` theme loads `docmd-theme-sky.css` with its custom styling on top of the default CSS
+- `ruby` theme loads `docmd-theme-ruby.css` with its custom styling on top of the default CSS
 
 You can further customize any chosen theme using the `theme.customCss` option in your `config.js` to add your own overrides or additional styles. See [Custom CSS & JS](/theming/custom-css-js/) for details.

package/package.json

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

package/src/assets/css/docmd-main.css

@@ -142,8 +142,9 @@
     flex-grow: 1;
     display: flex;
     flex-direction: column;
+    overflow: hidden;
   }
-  
+
   .page-header {
     padding: 15px 30px;
     border-bottom: 1px solid var(--header-border);

package/src/assets/css/docmd-theme-ruby.css

@@ -0,0 +1,606 @@
+/* docmd-theme-ruby.css - Ruby theme for docmd */
+
+/* Import Google Fonts for Ruby theme */
+@import url('https://fonts.googleapis.com/css2?family=Playfair+Display:wght@400;500;600;700&family=Source+Sans+Pro:wght@300;400;600;700&display=swap');
+
+:root [data-theme="light"] {
+  /* Font family */
+  --ruby-font-family-sans: 'Source Sans Pro', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+  --ruby-font-family-serif: 'Playfair Display', Georgia, 'Times New Roman', serif;
+  --ruby-font-family-mono: 'JetBrains Mono', 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
+  
+  /* Color palette - Light mode */
+  --ruby-primary: #b30000;         /* Deep ruby red */
+  --ruby-primary-light: #ffebee;   /* Very light red */
+  --ruby-primary-dark: #8e0000;    /* Darker ruby red */
+  --ruby-accent: #7b1fa2;          /* Complementary purple */
+  --ruby-accent-light: #f3e5f5;    /* Light purple */
+  --ruby-text: #2d2d2d;            /* Nearly black text */
+  --ruby-text-light: #5a5a5a;      /* Medium gray text */
+  --ruby-text-lightest: #757575;   /* Light gray text */
+  --ruby-background: #ffffff;      /* White background */
+  --ruby-background-alt: #fafafa;  /* Very light gray background */
+  --ruby-border: #e0e0e0;          /* Light gray border */
+  --ruby-border-light: #f0f0f0;    /* Very light gray border */
+  
+  /* Apply colors to CSS variables */
+  --bg-color: var(--ruby-background);
+  --text-color: var(--ruby-text);
+  --sidebar-bg: #f8f5f5;
+  --sidebar-text: var(--ruby-text-light);
+  --sidebar-link-active-bg: #f8e7e7;
+  --sidebar-link-active-text: var(--ruby-primary);
+  --link-color: var(--ruby-primary);
+  --border-color: var(--ruby-border);
+  --code-bg: var(--ruby-primary-light);
+  --code-text: var(--ruby-primary-dark);
+  --header-bg: var(--ruby-background);
+  --header-border: var(--ruby-border);
+  
+  /* Box shadows with ruby tint */
+  --shadow-sm: 0 2px 4px rgba(179, 0, 0, 0.05);
+  --shadow-md: 0 4px 8px rgba(179, 0, 0, 0.1);
+  --shadow-lg: 0 8px 16px rgba(179, 0, 0, 0.15);
+  
+  /* Image styling variables */
+  --image-border-color: var(--ruby-border);
+  --image-shadow: var(--shadow-md);
+  --image-caption-bg: var(--ruby-background-alt);
+  --image-caption-text: var(--ruby-text-light);
+  --image-hover-transform: translateY(-3px);
+  --image-hover-shadow: var(--shadow-lg);
+  --image-border-radius: 6px;
+  --image-transition: all 0.3s ease;
+}
+
+/* Dark mode */
+:root [data-theme="dark"] {
+  /* Color palette - Dark mode */
+  --ruby-primary: #ff5252;         /* Bright ruby red */
+  --ruby-primary-light: #3c1a1a;   /* Dark red background */
+  --ruby-primary-dark: #ff7b7b;    /* Lighter ruby red */
+  --ruby-accent: #ce93d8;          /* Light purple */
+  --ruby-accent-light: #2a1a2a;    /* Dark purple background */
+  --ruby-text: #f0f0f0;            /* Nearly white text */
+  --ruby-text-light: #c0c0c0;      /* Light gray text */
+  --ruby-text-lightest: #a0a0a0;   /* Medium gray text */
+  --ruby-background: #1a0a0a;      /* Very dark red-tinted background */
+  --ruby-background-alt: #2a1515;  /* Dark red-tinted background */
+  --ruby-border: #3a2020;          /* Dark red-tinted border */
+  --ruby-border-light: #2a1818;    /* Very dark red-tinted border */
+  
+  /* Apply colors to CSS variables */
+  --bg-color: var(--ruby-background);
+  --text-color: var(--ruby-text);
+  --sidebar-bg: #1a0a0a;
+  --sidebar-text: var(--ruby-text-light);
+  --sidebar-link-active-bg: #2a1515;
+  --sidebar-link-active-text: var(--ruby-primary);
+  --link-color: var(--ruby-primary);
+  --border-color: var(--ruby-border);
+  --code-bg: var(--ruby-primary-light);
+  --code-text: var(--ruby-text);
+  --header-bg: var(--ruby-background);
+  --header-border: var(--ruby-border);
+  
+  /* Box shadows for dark mode */
+  --shadow-sm: 0 2px 4px rgba(0, 0, 0, 0.3);
+  --shadow-md: 0 4px 8px rgba(0, 0, 0, 0.4);
+  --shadow-lg: 0 8px 16px rgba(0, 0, 0, 0.5);
+  
+  /* Image styling variables for dark mode */
+  --image-border-color: var(--ruby-border);
+  --image-shadow: 0 4px 8px rgba(0, 0, 0, 0.5);
+  --image-caption-bg: var(--ruby-background-alt);
+  --image-caption-text: var(--ruby-text-light);
+  --image-hover-transform: translateY(-3px);
+  --image-hover-shadow: 0 6px 12px rgba(0, 0, 0, 0.7);
+  --image-border-radius: 6px;
+  --image-transition: all 0.3s ease;
+}
+
+/* Apply theme styles */
+
+/* Typography improvements */
+body {
+  font-family: var(--ruby-font-family-sans);
+  line-height: 1.7;
+  letter-spacing: 0.01em;
+}
+
+h1, h2, h3, h4, h5, h6 {
+  font-family: var(--ruby-font-family-serif);
+  font-weight: 600;
+  line-height: 1.3;
+  margin-top: 2em;
+  margin-bottom: 0.7em;
+  color: var(--ruby-text);
+  letter-spacing: -0.01em;
+}
+
+h1 {
+  font-size: 2.5rem;
+  font-weight: 700;
+  margin-top: 0;
+  position: relative;
+  padding-bottom: 0.5rem;
+}
+
+h1::after {
+  content: "";
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  width: 60px;
+  height: 3px;
+  background: linear-gradient(90deg, var(--ruby-primary), var(--ruby-accent));
+  border-radius: 3px;
+}
+
+h2 {
+  font-size: 1.9rem;
+  border-bottom: 1px solid var(--ruby-border-light);
+  padding-bottom: 0.5rem;
+}
+
+h3 {
+  font-size: 1.6rem;
+}
+
+h4 {
+  font-size: 1.3rem;
+}
+
+a {
+  color: var(--link-color);
+  text-decoration: none;
+  transition: color 0.2s ease;
+  position: relative;
+}
+
+a:hover {
+  color: var(--ruby-primary-dark);
+}
+
+/* Stylish underline effect for links in content */
+.content-area a:not(.button):not(.no-underline)::after {
+  content: '';
+  position: absolute;
+  width: 100%;
+  height: 1px;
+  bottom: 0;
+  left: 0;
+  background: linear-gradient(90deg, var(--ruby-primary), var(--ruby-accent));
+  transform: scaleX(0);
+  transform-origin: bottom right;
+  transition: transform 0.3s ease;
+}
+
+.content-area a:not(.button):not(.no-underline):hover::after {
+  transform: scaleX(1);
+  transform-origin: bottom left;
+}
+
+p {
+  margin: 0.7em 0;
+  padding: 0.3em 0;
+  line-height: 1.8;
+}
+
+/* Sidebar refinements */
+.sidebar {
+  box-shadow: var(--shadow-sm);
+  border-right: 1px solid var(--ruby-border);
+}
+
+.sidebar-header {
+  border-bottom: 2px solid var(--ruby-border);
+  margin-bottom: 1.5rem;
+  padding-bottom: 1rem;
+}
+
+.sidebar nav li a {
+  border-radius: 4px;
+  margin-bottom: 3px;
+  transition: all 0.3s ease;
+  padding: 0.6rem 0.8rem;
+  font-weight: 400;
+}
+
+.sidebar nav li a:hover {
+  background-color: var(--sidebar-link-active-bg);
+  color: var(--ruby-primary);
+  transform: translateX(3px);
+}
+
+.sidebar nav li a.active {
+  background-color: var(--sidebar-link-active-bg);
+  color: var(--sidebar-link-active-text);
+  font-weight: 600;
+  border-left: 3px solid var(--ruby-primary);
+}
+
+/* Content area */
+.content-area {
+  padding: 2.5rem 5%;
+}
+
+/* Code blocks */
+pre {
+  background-color: var(--code-bg);
+  border-radius: 6px;
+  margin: 1.5em 0;
+  padding: 1.25em;
+  box-shadow: var(--shadow-sm);
+  border-left: 3px solid var(--ruby-primary);
+}
+
+code {
+  font-family: var(--ruby-font-family-mono);
+  font-size: 0.9em;
+  border-radius: 4px;
+  padding: 0.2em 0.4em;
+}
+
+/* Tables */
+table {
+  width: 100%;
+  border-collapse: separate;
+  border-spacing: 0;
+  margin: 1.5em 0;
+  border-radius: 6px;
+  overflow: hidden;
+  box-shadow: var(--shadow-sm);
+}
+
+th {
+  background-color: var(--ruby-primary-light);
+  color: var(--ruby-primary-dark);
+  text-align: left;
+  font-weight: 600;
+  padding: 0.75rem 1rem;
+  border-bottom: 2px solid var(--ruby-border);
+}
+
+td {
+  padding: 0.75rem 1rem;
+  border-top: 1px solid var(--ruby-border-light);
+}
+
+tr:hover {
+  background-color: var(--ruby-background-alt);
+}
+
+/* Custom container styling for Ruby theme */
+.docmd-container {
+  padding: 1.2rem 1.5rem;
+  margin: 1.75rem 0;
+  border-radius: 6px;
+  border: 1px solid var(--ruby-border-light);
+  background-color: var(--ruby-background);
+  box-shadow: var(--shadow-sm);
+  position: relative;
+  overflow: hidden;
+}
+
+/* Add gem-like facet to containers */
+.docmd-container::before {
+  content: '';
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 3px;
+  background: linear-gradient(90deg, var(--ruby-primary), var(--ruby-accent));
+}
+
+/* Callouts */
+.callout {
+  position: relative;
+  border: none;
+  border-left: 4px solid;
+  background-color: var(--ruby-background-alt);
+}
+
+.callout-title {
+  font-family: var(--ruby-font-family-serif);
+  font-weight: 600;
+  margin-bottom: 0.75em;
+  display: flex;
+  align-items: center;
+  font-size: 1.1em;
+}
+
+.callout-title::before {
+  margin-right: 0.5rem;
+  font-size: 1.1em;
+}
+
+.callout-info {
+  border-left-color: var(--ruby-primary);
+}
+
+.callout-info .callout-title {
+  color: var(--ruby-primary);
+}
+
+.callout-warning {
+  border-left-color: #f39c12;
+}
+
+.callout-warning .callout-title {
+  color: #f39c12;
+}
+
+.callout-tip {
+  border-left-color: #2ecc71;
+}
+
+.callout-tip .callout-title {
+  color: #2ecc71;
+}
+
+.callout-danger {
+  border-left-color: #e74c3c;
+}
+
+.callout-danger .callout-title {
+  color: #e74c3c;
+}
+
+.callout-success {
+  border-left-color: #2ecc71;
+}
+
+.callout-success .callout-title {
+  color: #2ecc71;
+}
+
+/* Cards with gem-like styling */
+.card {
+  border: none;
+  border-radius: 6px;
+  background: linear-gradient(135deg, var(--ruby-background) 0%, var(--ruby-background-alt) 100%);
+  box-shadow: var(--shadow-md);
+  transition: all 0.3s ease;
+  overflow: hidden;
+}
+
+.card:hover {
+  transform: translateY(-5px);
+  box-shadow: var(--shadow-lg);
+}
+
+.card .card-title {
+  font-family: var(--ruby-font-family-serif);
+  font-weight: 600;
+  padding: 1rem 1.5rem;
+  margin: 0;
+  background: linear-gradient(90deg, var(--ruby-primary-light), var(--ruby-accent-light));
+  color: var(--ruby-primary-dark);
+  border-bottom: 1px solid var(--ruby-border);
+}
+
+.card .card-content {
+  padding: 1rem 1.5rem;
+}
+
+/* Steps styling */
+.steps {
+  counter-reset: step-counter;
+  position: relative;
+  padding-left: 1rem;
+}
+
+.steps h4 {
+  position: relative;
+  padding-left: 2.5rem;
+  margin-top: 2rem;
+  margin-bottom: 1rem;
+  font-family: var(--ruby-font-family-serif);
+}
+
+.steps h4::before {
+  content: counter(step-counter);
+  counter-increment: step-counter;
+  position: absolute;
+  left: 0;
+  top: 50%;
+  transform: translateY(-50%);
+  width: 1.8rem;
+  height: 1.8rem;
+  background: linear-gradient(135deg, var(--ruby-primary) 0%, var(--ruby-accent) 100%);
+  color: white;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 0.9rem;
+  font-weight: 600;
+  box-shadow: var(--shadow-sm);
+}
+
+/* Buttons */
+button, .button {
+  background: linear-gradient(135deg, var(--ruby-primary) 0%, var(--ruby-accent) 100%);
+  color: white;
+  border: none;
+  padding: 0.6rem 1.2rem;
+  border-radius: 4px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all 0.3s ease;
+  box-shadow: var(--shadow-sm);
+}
+
+button:hover, .button:hover {
+  box-shadow: var(--shadow-md);
+  transform: translateY(-2px);
+}
+
+.theme-toggle-button {
+  background: transparent;
+  color: var(--ruby-text-light);
+  box-shadow: none;
+}
+
+.theme-toggle-button:hover {
+  background: var(--ruby-background-alt);
+  color: var(--ruby-primary);
+  box-shadow: var(--shadow-sm);
+  transform: translateY(0);
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+  .content-area {
+    padding: 1.5rem 1rem;
+  }
+  
+  h1 {
+    font-size: 2rem;
+  }
+  
+  h2 {
+    font-size: 1.6rem;
+  }
+  
+  h3 {
+    font-size: 1.3rem;
+  }
+}
+
+/* Image styling */
+img {
+  max-width: 100%;
+  height: auto;
+  border-radius: var(--image-border-radius);
+  transition: var(--image-transition);
+}
+
+img.with-border {
+  border: 1px solid var(--image-border-color);
+  padding: 4px;
+}
+
+img.with-shadow {
+  box-shadow: var(--image-shadow);
+}
+
+img.with-shadow:hover {
+  box-shadow: var(--image-hover-shadow);
+  transform: var(--image-hover-transform);
+}
+
+figure {
+  margin: 1.5em 0;
+  text-align: center;
+  transition: var(--image-transition);
+}
+
+figure:hover {
+  transform: var(--image-hover-transform);
+}
+
+figure img {
+  max-width: 100%;
+  border-radius: var(--image-border-radius);
+}
+
+figcaption {
+  background-color: var(--image-caption-bg);
+  color: var(--image-caption-text);
+  padding: 0.5em;
+  font-size: 0.9em;
+  border-radius: 0 0 var(--image-border-radius) var(--image-border-radius);
+  font-style: italic;
+}
+
+/* Image gallery */
+.image-gallery {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+  gap: 1rem;
+  margin: 1.5em 0;
+}
+
+.image-gallery figure {
+  margin: 0;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  border-radius: var(--image-border-radius);
+  overflow: hidden;
+  box-shadow: var(--shadow-sm);
+}
+
+.image-gallery figure:hover {
+  box-shadow: var(--shadow-md);
+}
+
+.image-gallery img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  border-radius: var(--image-border-radius) var(--image-border-radius) 0 0;
+  transition: transform 0.3s ease;
+}
+
+.image-gallery figcaption {
+  padding: 0.5rem;
+  background-color: var(--image-caption-bg);
+  color: var(--image-caption-text);
+  font-size: 0.85rem;
+  border-radius: 0;
+}
+
+/* Zoom effect for gallery images */
+.image-gallery.zoom img {
+  transition: transform 0.3s ease;
+}
+
+.image-gallery.zoom figure:hover img {
+  transform: scale(1.05);
+}
+
+/* Lightbox image styling */
+img.lightbox {
+  cursor: zoom-in;
+}
+
+/* Framed image styling */
+img.framed {
+  border: 8px solid white;
+  box-shadow: 0 0 0 1px var(--ruby-border), var(--shadow-md);
+  border-radius: 3px;
+}
+
+/* Polaroid-style image */
+figure.polaroid {
+  background: white;
+  padding: 10px 10px 20px;
+  box-shadow: var(--shadow-md);
+  border-radius: 3px;
+}
+
+figure.polaroid img {
+  border-radius: 2px;
+}
+
+figure.polaroid figcaption {
+  background: white;
+  color: var(--ruby-text);
+  font-family: var(--ruby-font-family-serif);
+  font-style: italic;
+}
+
+/* Mobile responsiveness for images */
+@media (max-width: 768px) {
+  .image-gallery {
+    grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
+  }
+  
+  .image-gallery img {
+    height: 120px;
+  }
+} 

package/src/commands/dev.js

@@ -44,6 +44,9 @@ async function startDevServer(configPathOption, options = { preserve: false }) {
   let paths = resolveConfigPaths(config);
 
   // docmd's internal templates and assets (for live dev of docmd itself)
+  const DOCMD_COMMANDS_DIR = path.resolve(__dirname, '..', 'commands');
+  const DOCMD_CORE_DIR = path.resolve(__dirname, '..', 'core');
+  const DOCMD_PLUGINS_DIR = path.resolve(__dirname, '..', 'plugins');
   const DOCMD_TEMPLATES_DIR = path.resolve(__dirname, '..', 'templates');
   const DOCMD_ASSETS_DIR = path.resolve(__dirname, '..', 'assets');
 
@@ -199,13 +202,13 @@ async function startDevServer(configPathOption, options = { preserve: false }) {
   }
 
   // Add internal paths for docmd development (not shown to end users)
-  const internalPaths = [DOCMD_TEMPLATES_DIR, DOCMD_ASSETS_DIR];
+  const internalPaths = [DOCMD_TEMPLATES_DIR, DOCMD_ASSETS_DIR, DOCMD_COMMANDS_DIR, DOCMD_CORE_DIR, DOCMD_PLUGINS_DIR];
   
   // Only in development environments, we might want to watch internal files too
   if (process.env.DOCMD_DEV === 'true') {
     watchedPaths.push(...internalPaths);
   }
-
+  
   console.log(`👀 Watching for changes in:`);
   console.log(`    - Source: ${formatPathForDisplay(paths.srcDirToWatch, CWD)}`);
   console.log(`    - Config: ${formatPathForDisplay(paths.configFileToWatch, CWD)}`);

package/src/commands/init.js

@@ -35,6 +35,7 @@ module.exports = {
   // Custom JavaScript Files
   customJs: [  // Array of paths to custom JS files, loaded at end of body
     // '/assets/js/custom-script.js', // Paths relative to outputDir root
+    '/assets/js/docmd-image-lightbox.js', // Image lightbox functionality
   ],
 
   // Plugins Configuration
@@ -85,6 +86,7 @@ module.exports = {
           { title: 'Documentation', path: 'https://docmd.mgks.dev', icon: 'scroll', external: true },
           { title: 'Installation', path: 'https://docmd.mgks.dev/getting-started/installation', icon: 'download', external: true },
           { title: 'Basic Usage', path: 'https://docmd.mgks.dev/getting-started/basic-usage', icon: 'play', external: true },
+          { title: 'Content', path: 'https://docmd.mgks.dev/content', icon: 'layout-template', external: true },
         ],
       },
       // External links:

package/src/templates/layout.ejs

@@ -6,7 +6,7 @@
 
     <%- metaTagsHtml || '' %> <%# SEO Plugin Meta Tags %>
 
-    <title><%= pageTitle %> | <%= siteTitle %></title>
+    <title><%= pageTitle %> : <%= siteTitle %></title>
     <% if (description && !(metaTagsHtml && metaTagsHtml.includes('name="description"'))) { %>
       <meta name="description" content="<%= description %>">
     <% } %>