@mgks/docmd 0.1.3 → 0.2.0

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"`
@@ -50,6 +50,7 @@ Examples of custom fields you *might* add (these are not built-in features):
 *   `order`: 2 (For custom sorting of pages within a section, if you implement logic for it)
 *   `draft`: true (To mark a page as a draft, if you implement logic to exclude drafts from builds)
 *   `tags`: ["tag1", "tag2"]
+*   `permalink`: "https://example.com/your-canonical-url/" (Sets the canonical URL for SEO purposes)
 
 ## Example Usage
 
@@ -68,9 +69,8 @@ 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.
 
-Using frontmatter consistently ensures your pages are well-defined, SEO-friendly, and integrate smoothly with `docmd`'s navigation and theming systems.
-```
+Using frontmatter consistently ensures your pages are well-defined, SEO-friendly, and integrate smoothly with `docmd`'s navigation and theming systems.

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,13 +7,9 @@ components:
   favicon: true
   css: false
   theme: false
-  scripts: true
-  themeToggle: false
-  lightbox: false
+  scripts: 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">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <link rel="stylesheet" href="/assets/css/welcome.css">
   <script>
     // Initialize theme from localStorage or system preference
@@ -26,7 +22,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 +30,7 @@ customHead: |
       document.body.setAttribute('data-theme', newTheme);
       localStorage.setItem('docmd-theme', newTheme);
     }
-    
+
     // Run on page load
     document.addEventListener('DOMContentLoaded', initTheme);
   </script>
@@ -101,8 +97,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,26 +112,26 @@ 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>
   
   <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">
+        <img src="/assets/images/preview-light-1.webp" alt="docmd documentation preview" class="light-img" loading="lazy">
+        <img src="/assets/images/preview-dark-1.webp" alt="docmd documentation preview" class="dark-img" loading="lazy">
       </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">
+        <img src="/assets/images/preview-light-2.webp" alt="docmd documentation preview" class="light-img" loading="lazy">
+        <img src="/assets/images/preview-dark-2.webp" alt="docmd documentation preview" class="dark-img" loading="lazy">
       </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">
+        <img src="/assets/images/preview-light-3.webp" alt="docmd documentation preview" class="light-img" loading="lazy">
+        <img src="/assets/images/preview-dark-3.webp" alt="docmd documentation preview" class="dark-img" loading="lazy">
       </div>
     </div>
   </div>
-</div> 
+</div>

package/docs/plugins/seo.md

@@ -62,6 +62,7 @@ image: "/assets/images/widgets/super-widget-social.jpg" # Used for og:image and
 ogType: "article" # Specify Open Graph type, e.g., article, website
 twitterCreator: "@widgetMaster"
 keywords: "widget, configuration, advanced, performance, security" # Optional, some argue keywords meta tag is less relevant now
+permalink: "https://example.com/docs/widgets/advanced-configuration" # Canonical URL
 ---
 
 # Advanced Widget Configuration
@@ -75,5 +76,6 @@ Supported frontmatter fields that the `seo` plugin may look for:
 *   `twitterCard` (Overrides `config.seo.twitter.cardType` for this page)
 *   `twitterCreator` (Overrides `config.seo.twitter.creatorUsername` for this page)
 *   `noindex` (Boolean): If `true`, adds `<meta name="robots" content="noindex">` to discourage search engines from indexing this specific page.
+*   `permalink` (String): If provided, sets a canonical URL for the page. This is useful when you have duplicate content across different URLs and want to indicate the preferred version. If not specified, the page's URL will be used as the canonical URL. (Note: `canonicalUrl` is also supported for backward compatibility)
 
 By configuring the `seo` plugin and utilizing frontmatter effectively, you can significantly improve how your documentation is presented and discovered online.

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,72 @@ 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', 'retro'
+    defaultMode: 'light', // or 'dark' to set as landing mode
     // ...
   },
   // ...
 };
 ```
 
+## 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
-    // ...
-  },
-  // ...
-};
-```
-
-Users can switch between modes using the toggle button in the sidebar, and their preference will be saved in localStorage for future visits.
+## 3. `ruby` Theme
+
+*   **`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.
+
+## 4. `retro` Theme
+
+*   **`theme.name: 'retro'`**
+*   **Description:** A nostalgic theme inspired by 1980s-90s computing aesthetics. It features:
+    *   Terminal-style black backgrounds with phosphor green text in dark mode
+    *   Light mode with dark green text on light gray backgrounds
+    *   Monospace typography (Fira Code) for authentic retro feel
+    *   Neon accent colors (cyan, pink, amber) with glow effects
+    *   Animated scanlines and CRT flicker effects
+    *   Terminal-style code blocks with `[TERMINAL]` labels
+    *   Retro-styled containers with pixel-art inspired elements
+    *   Blinking cursor effects on links and active elements
+*   **When to use:** Perfect for developer tools, gaming documentation, tech blogs with vintage computing focus, or anyone wanting a unique, eye-catching retro aesthetic.
 
 ## 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
+- `retro` theme loads `docmd-theme-retro.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/docs/theming/light-dark-mode.md

@@ -16,9 +16,10 @@ You can set the default theme for your site in the `config.js` file:
 module.exports = {
   // ... other config ...
   theme: {
-    name: 'default', // or 'sky'
+    name: 'default', // or 'sky', 'ruby', 'retro'
     defaultMode: 'dark', // Can be 'light' or 'dark'
     enableModeToggle: true, // Enable the toggle button in the UI
+    positionMode: 'bottom', // 'top' or 'bottom' - where to show the toggle
   },
   // ...
 };
@@ -26,7 +27,9 @@ module.exports = {
 
 * `defaultMode: 'light'`: The site will initially render with the light color scheme.
 * `defaultMode: 'dark'`: The site will initially render with the dark color scheme.
-* `enableModeToggle: true`: Shows a toggle button in the sidebar for users to switch modes.
+* `enableModeToggle: true`: Shows a toggle button for users to switch modes.
+* `positionMode: 'bottom'`: Places the toggle button at the bottom of the sidebar (default).
+* `positionMode: 'top'`: Places the toggle button in the page header (top right).
 
 If `defaultMode` is not specified, it defaults to `'light'`.
 
@@ -62,16 +65,22 @@ body {
 
 ## User Preference Toggle
 
-When `enableModeToggle` is set to `true`, a toggle button appears in the sidebar that allows users to switch between light and dark modes:
+When `enableModeToggle` is set to `true`, a toggle button appears that allows users to switch between light and dark modes. The position of this button is controlled by the `positionMode` setting:
 
 ```javascript
 // config.js
 theme: {
   defaultMode: 'light',
   enableModeToggle: true, // Shows the toggle button
+  positionMode: 'bottom', // 'bottom' (sidebar) or 'top' (header)
 },
 ```
 
+### Toggle Button Positions
+
+- **`positionMode: 'bottom'`** (default): The toggle button appears at the bottom of the sidebar
+- **`positionMode: 'top'`**: The toggle button appears in the page header (top right corner)
+
 The toggle button uses Lucide icons (`sun` and `moon`) to indicate the current mode and what will happen when clicked.
 
 ### User Preference Persistence

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@mgks/docmd",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Generate beautiful, lightweight static documentation sites directly from your Markdown files. Zero clutter, just content.",
   "main": "src/index.js",
   "bin": {
-    "docmd": "./bin/docmd.js"
+    "docmd": "bin/docmd.js"
   },
   "scripts": {
     "start": "node ./bin/docmd.js dev",
@@ -43,9 +43,12 @@
     "gray-matter": "^4.0.3",
     "highlight.js": "^11.11.1",
     "lucide-static": "^0.508.0",
-    "markdown-it": "^14.1.0",
+    "markdown-it-abbr": "^2.0.0",
     "markdown-it-attrs": "^4.3.1",
     "markdown-it-container": "^4.0.0",
+    "markdown-it-deflist": "^3.0.0",
+    "markdown-it-footnote": "^4.0.0",
+    "markdown-it-task-lists": "^2.1.1",
     "ws": "^8.17.0"
   },
   "devDependencies": {
@@ -53,5 +56,8 @@
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-node": "^11.1.0",
     "prettier": "^3.2.5"
+  },
+  "directories": {
+    "doc": "docs"
   }
 }