@mgks/docmd 0.2.0 → 0.2.1

package/assets/css/welcome.css

@@ -1,66 +1,6 @@
-:root{--primary-color:#047bf1;--primary-hover:#026ed9;--text-color:#333;--text-light:#666;--bg-color:#fff;--bg-secondary:#f8f9fa;--border-color:#eaeaea;--shadow-color:#00000014;--container-padding:5rem}
-@media (prefers-color-scheme: dark) {
-:root{--primary-color:#047bf1;--primary-hover:#026ed9;--text-color:#e0e0e0;--text-light:#aaa;--bg-color:#121212;--bg-secondary:#1e1e1e;--border-color:#333;--shadow-color:#0000004d}
-}
-[data-theme="light"]{--primary-color:#047bf1;--primary-hover:#026ed9;--text-color:#333;--text-light:#666;--bg-color:#fff;--bg-secondary:#f8f9fa;--border-color:#eaeaea;--shadow-color:#00000059}
-[data-theme="dark"]{--primary-color:#1955b6;--primary-hover:#084dbd;--text-color:#e0e0e0;--text-light:#aaa;--bg-color:#121212;--bg-secondary:#1e1e1e;--border-color:#333;--shadow-color:#000000de}
-*{margin:0;padding:0;box-sizing:border-box}
-body{font-family:'Inter',-apple-system,BlinkMacSystemFont,sans-serif;line-height:1.5;color:var(--text-color);background-color:var(--bg-color);height:100vh;display:flex;overflow:hidden}
-.landing-container{display:flex;width:100%;height:100%;padding:0 var(--container-padding);max-width:1600px;margin:0 auto}
-.content-side{flex:1;padding:3rem 2rem 3rem 0;display:flex;flex-direction:column;justify-content:center}
-.preview-side{flex:1;display:flex;align-items:center;justify-content:flex-start;position:relative;overflow:visible}
-.header-top{position:absolute;top:2rem;right:3rem;z-index:100}
-.theme-toggle{background:var(--bg-secondary);border:1px solid var(--border-color);color:var(--text-color);width:40px;height:40px;border-radius:50%;display:flex;align-items:center;justify-content:center;cursor:pointer;transition:all .2s ease}
-.theme-toggle:hover{background:var(--border-color)}
-.logo{margin-bottom:1.5rem;display:flex;align-items:center}
-.logo svg{height:48px;width:auto}
-.logo-text{font-family:'PT Mono',monospace;font-weight:700;font-size:2em;margin-left:.25em}
-h1{font-size:3rem;font-weight:700;margin-bottom:1rem;letter-spacing:-.02em}
-.tagline{font-size:1.25rem;color:var(--text-light);margin-bottom:2rem;font-weight:400}
-.features{display:grid;grid-template-columns:repeat(2,1fr);gap:1.5rem;margin-bottom:2rem}
-.feature{display:flex;align-items:flex-start;gap:.75rem}
-.feature-icon{background-color:var(--primary-color);color:#fff;width:32px;height:32px;border-radius:6px;display:flex;align-items:center;justify-content:center;flex-shrink:0}
-.feature-text{font-size:.9rem}
-.feature-text strong{display:block;margin-bottom:.25rem}
-.buttons{display:flex;gap:1rem;margin-bottom:2rem}
-.btn{display:inline-flex;align-items:center;gap:.5rem;padding:.75rem 1.5rem;border-radius:8px;font-weight:600;font-size:1rem;text-decoration:none;transition:all .2s ease}
-.btn-primary{background-color:var(--primary-color);color:#fff;border:none}
-.btn-primary:hover{background-color:var(--primary-hover)}
-.btn-secondary{background-color:var(--bg-secondary);color:var(--text-color);border:1px solid var(--border-color)}
-.btn-secondary:hover{background-color:var(--border-color)}
-.social-links{display:flex;gap:1rem;padding:0 .25em}
-.social-link{color:var(--text-light);transition:color .2s ease}
-.social-link:hover{color:var(--primary-color)}
-.preview-stack{position:relative;width:100%;height:400px;transform:translateX(15%);perspective:1000px}
-.preview-image{position:absolute;width:100%;max-width:700px;height:400px;border-radius:20px;box-shadow:0 25px 50px -12px var(--shadow-color);transition:all .3s ease;overflow:hidden}
-.preview-image img{width:100%;height:100%;object-fit:cover;object-position:left top;border-radius:8px;pointer-events:none}
-.preview-image.top{z-index:3;transform:rotate(3deg) translateY(-10%) translateX(7%)}
-.preview-image.middle{z-index:2;transform:rotate(-3deg) translateY(1%) translateX(-2%)}
-.preview-image.bottom{z-index:1;transform:rotate(-8deg) translateY(10%) translateX(-10%)}
-body[data-theme="light"] .preview-image .light-img{display:block}
-body[data-theme="light"] .preview-image .dark-img{display:none}
-body[data-theme="dark"] .preview-image .light-img{display:none}
-body[data-theme="dark"] .preview-image .dark-img{display:block}
-@media (max-width: 1400px) {
-:root{--container-padding:3rem}
-.preview-stack{transform:translateX(15%)}
-}
-@media (max-width: 1200px) {
-:root{--container-padding:2rem}
-.preview-side{display:none}
-.content-side{max-width:100%;padding:3rem 0}
-.header-top{right:2rem}
-}
-@media (max-width: 768px) {
-:root{--container-padding:1.5rem}
-body{overflow:auto}
-.content-side{padding:2rem 0}
-h1{font-size:2.5rem}
-.features{grid-template-columns:1fr}
-.buttons{flex-direction:column}
-.header-top{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{color:#cd2727}
+/*
+ * Source file from the docmd project — https://github.com/mgks/docmd
+ * Configuration for the docmd project's own documentation
+ */
+
+:root,html[data-theme=light]{--primary-color:#047bf1;--primary-hover:#026ed9;--text-color:#333;--text-light:#666;--bg-color:#fff;--bg-secondary:#f8f9fa;--border-color:#eaeaea}.theme-toggle,body{color:var(--text-color);display:flex}.logo-text,h1{font-weight:700}.install-code pre,.logo-text{font-family:'PT Mono',monospace}:root{--shadow-color:#00000014;--container-padding:5rem}@media (prefers-color-scheme:dark){:root{--primary-color:#047bf1;--primary-hover:#026ed9;--text-color:#e0e0e0;--text-light:#aaa;--bg-color:#121212;--bg-secondary:#1e1e1e;--border-color:#333;--shadow-color:#0000004d}}[data-theme=light]{--shadow-color:#00000059}[data-theme=dark]{--primary-color:#1955b6;--primary-hover:#084dbd;--text-color:#e0e0e0;--text-light:#aaa;--bg-color:#121212;--bg-secondary:#1e1e1e;--border-color:#333;--shadow-color:#000000de}*{margin:0;padding:0;box-sizing:border-box}body{font-family:Inter,-apple-system,BlinkMacSystemFont,sans-serif;line-height:1.5;background-color:var(--bg-color);height:100vh;overflow:hidden}.landing-container{display:flex;width:100%;height:100%;padding:0 var(--container-padding);max-width:1600px;margin:0 auto}.content-side{flex:1;padding:3rem 2rem 3rem 0;display:flex;flex-direction:column;justify-content:center}.preview-side{flex:1;display:flex;align-items:center;justify-content:flex-start;position:relative;overflow:visible}.header-top{position:absolute;top:2rem;right:3rem;z-index:100}.theme-toggle{background:var(--bg-secondary);border:1px solid var(--border-color);width:40px;height:40px;border-radius:50%;align-items:center;justify-content:center;cursor:pointer;transition:.2s}.theme-toggle:hover{background:var(--border-color)}.logo{margin-bottom:1.5rem;display:flex;align-items:center}.buttons,.features,.install-section,.tagline{margin-bottom:2rem}.logo svg{height:48px;width:auto}.logo-text{font-size:2em;margin-left:.25em}h1{font-size:3rem;margin-bottom:1rem;letter-spacing:-.02em}.tagline{font-size:1.25rem;color:var(--text-light);font-weight:400}.btn-primary,.feature-icon{background-color:var(--primary-color);color:#fff}.features{display:grid;grid-template-columns:repeat(2,1fr);gap:1.5rem}.feature{display:flex;align-items:flex-start;gap:.75rem}.feature-icon{width:32px;height:32px;border-radius:6px;display:flex;align-items:center;justify-content:center;flex-shrink:0}.feature-text{font-size:.9rem}.feature-text strong{display:block;margin-bottom:.25rem}.buttons{display:flex;gap:1rem}.btn{display:inline-flex;align-items:center;gap:.5rem;padding:.75rem 1.5rem;border-radius:8px;font-weight:600;font-size:1rem;text-decoration:none;transition:.2s}.btn-primary{border:none}.btn-secondary,.install-code pre{background-color:var(--bg-secondary);border:1px solid var(--border-color)}.btn-primary:hover{background-color:var(--primary-hover)}.btn-secondary{color:var(--text-color)}.btn-secondary:hover{background-color:var(--border-color)}.social-links{display:flex;gap:1rem;padding:0 .25em}.social-link{color:var(--text-light);transition:color .2s}.social-link:hover{color:var(--primary-color)}.preview-stack{position:relative;width:100%;height:400px;transform:translateX(15%);perspective:1000px}.preview-image{position:absolute;width:100%;max-width:700px;height:400px;border-radius:20px;box-shadow:0 25px 50px -12px var(--shadow-color);transition:.3s;overflow:hidden}.preview-image img{width:100%;height:100%;object-fit:cover;object-position:left top;border-radius:8px;pointer-events:none}.preview-image.top{z-index:3;transform:rotate(3deg) translateY(-10%) translateX(7%)}.preview-image.middle{z-index:2;transform:rotate(-3deg) translateY(1%) translateX(-2%)}.preview-image.bottom{z-index:1;transform:rotate(-8deg) translateY(10%) translateX(-10%)}[data-theme=dark] .preview-image .dark-img,[data-theme=light] .preview-image .light-img{display:block}[data-theme=dark] .preview-image .light-img,[data-theme=light] .preview-image .dark-img{display:none}@media (max-width:1400px){:root{--container-padding:3rem}.preview-stack{transform:translateX(15%)}}@media (max-width:1200px){:root{--container-padding:2rem}.preview-side{display:none}.content-side{max-width:100%;padding:3rem 0}.header-top{right:2rem}}@media (max-width:768px){:root{--container-padding:1.5rem}body{overflow:auto}.content-side{padding:2rem 0}.features{grid-template-columns:1fr}.buttons{flex-direction:column}.header-top{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{color:#cd2727}.install-code{position:relative;display:inline-block}.install-code pre{border-radius:8px;padding:1rem 3.5rem 1rem 1rem;margin:0;font-size:.9rem;color:var(--text-color)}.install-code code{background:0 0;padding:0;color:inherit}.copy-button{position:absolute;top:.5rem;right:.5rem;background:var(--bg-color);border:1px solid var(--border-color);border-radius:4px;padding:.5rem;cursor:pointer;transition:.2s;color:var(--text-light)}.copy-button:hover{background:var(--border-color);color:var(--text-color)}

package/config.js

@@ -1,4 +1,6 @@
-// config.js (for docmd's own documentation)
+// Source file from the docmd project — https://github.com/mgks/docmd
+
+// Configuration for the docmd project's own documentation
 module.exports = {
   // Core Site Metadata
   siteTitle: 'docmd',
@@ -26,10 +28,11 @@ module.exports = {
 
   // Theme Configuration
   theme: {
-    name: 'sky',            // Themes: 'default', 'sky'
+    name: 'sky',            // Themes: 'default', 'sky', 'retro', 'ruby'
     defaultMode: 'light',   // Initial color mode: 'light' or 'dark'
     enableModeToggle: true, // Show UI button to toggle light/dark modes
-    positionMode: 'top', // 'top' or 'bottom' for the theme toggle
+    positionMode: 'top',    // 'top' or 'bottom' for the theme toggle
+    codeHighlight: true,   // Enable/disable codeblock highlighting and import of highlight.js
     customCss: [            // Array of paths to custom CSS files
       // '/assets/css/custom.css', // Custom TOC styles
     ],
@@ -42,13 +45,15 @@ module.exports = {
 
   // Content Processing
   autoTitleFromH1: true, // Set to true to automatically use the first H1 as page title
+  copyCode: true, // Enable/disable the copy code button on code blocks
 
   // Plugins Configuration (Object format)
   // Plugins are configured here. docmd will look for these keys.
   plugins: {
     // SEO Plugin Configuration
-    // Most SEO data is pulled from page frontmatter (title, description, image, etc.)
-    // These are fallbacks or site-wide settings.
+    // These are site-wide fallbacks. For detailed per-page SEO controls,
+    // including structured data (LD+JSON), use the `seo` key in your page's frontmatter.
+    // See the SEO plugin documentation for all available frontmatter options.
     seo: {
       // Default meta description if a page doesn't have one in its frontmatter
       defaultDescription: 'docmd is a Node.js command-line tool for generating beautiful, lightweight static documentation sites from Markdown files.',

package/docs/configuration.md

@@ -44,6 +44,7 @@ module.exports = {
   ],
 
   autoTitleFromH1: true,
+  copyCode: true,
 
   sponsor: {
     enabled: true,
@@ -141,6 +142,11 @@ module.exports = {
     // ---
     ```
 
+### `copyCode`
+* **Type:** `Boolean`
+* **Default:** `true`
+* **Description:** If `true`, a "Copy" button will be added to the top-right corner of all code blocks, allowing users to easily copy the code to their clipboard with a single click. **Note:** This setting only applies to regular pages. For noStyle pages, copy code functionality must be explicitly enabled via the `components.mainScripts: true` setting.
+
 ## `sidebar` (Object)
 
 Configures the behavior of the sidebar.
@@ -186,7 +192,7 @@ Configures the visual theme of your site.
 ### `theme.customCss`
 *   **Type:** `Array` of `String`
 *   **Default:** `[]` (empty array)
-*   **Description:** An array of paths to your custom CSS files. These files will be linked in the `<head>` of every page *after* the main theme CSS, allowing you to override or extend styles.
+*   **Description:** An array of paths to your custom CSS files. These files will be linked in the `<head>` of every regular page *after* the main theme CSS, allowing you to override or extend styles. **Note:** For noStyle pages, custom CSS must be explicitly enabled via `components.customCss: true`.
 *   **Paths:** Should be relative to the `outputDir` root (e.g., `'/css/my-styles.css'`). You are responsible for ensuring these files exist at the specified location in your final `site/` output (e.g., by placing them in an assets folder that `docmd` copies, or in your project's static assets if your `srcDir` is part of a larger project).
 *   **Example:** `customCss: ['/assets/css/custom-branding.css']`
 
@@ -197,7 +203,7 @@ Configures the visual theme of your site.
 ## `customJs` (Array of String)
 *   **Type:** `Array` of `String`
 *   **Default:** `[]`
-*   **Description:** An array of paths to your custom JavaScript files. These files will be included as `<script>` tags just before the closing `</body>` tag on every page.
+*   **Description:** An array of paths to your custom JavaScript files. These files will be included as `<script>` tags just before the closing `</body>` tag on every regular page. **Note:** For noStyle pages, custom JavaScript must be explicitly enabled via `components.customJs: true`.
 *   **Paths:** Should be relative to the `outputDir` root (e.g., `'/js/my-analytics-alternative.js'`).
 *   **Example:** `customJs: ['/assets/js/interactive-component.js']`
 
@@ -222,11 +228,11 @@ Configures the visual theme of your site.
     *   `external` (Boolean, Optional): If set to `true`, the `path` is treated as an absolute external URL and the link will open in a new tab (`target="_blank"`). Defaults to `false`.
 
 ## `footer` (String, Optional)
-*   **Description:** Custom footer text (Markdown supported).
+*   **Description:** Custom footer text (Markdown supported). **Note:** For noStyle pages, the footer must be explicitly enabled via `components.footer: true`.
 
 ## `sponsor` (Object, Optional)
 *   **Type:** `Object`
-*   **Description:** Configures a sponsor ribbon that appears in the bottom-right corner of every page.
+*   **Description:** Configures a sponsor ribbon that appears in the bottom-right corner of every regular page. **Note:** For noStyle pages, the sponsor ribbon must be explicitly enabled via `components.branding: true`.
 *   **Properties:**
     *   `enabled` (Boolean, Optional): Whether to show the sponsor ribbon. Defaults to `true` if the sponsor object is provided.
     *   `title` (String, Optional): Text to display on the ribbon. Defaults to `'Sponsor the Project'`.
@@ -242,6 +248,6 @@ Configures the visual theme of your site.
 *   **Note:** The ribbon is positioned fixed in the bottom-right corner and includes a heart icon with a subtle animation.
 
 ## `favicon` (String, Optional)
-*   **Description:** Path to your favicon file, relative to `outputDir` root.
+*   **Description:** Path to your favicon file, relative to `outputDir` root. **Note:** For noStyle pages, the favicon must be explicitly enabled via `components.favicon: true`.
 
 This file needs significant detail for each new option, explaining its purpose, type, default value, and how to use it with examples.

package/docs/content/custom-containers.md

@@ -0,0 +1,24 @@
+---
+title: "Custom Containers"
+description: "Enhance your documentation with special components like callouts, cards, and steps using docmd's custom container syntax."
+noStyle: true
+components:
+  meta: false
+  favicon: true
+  css: false
+  theme: false
+  scripts: false
+customHead: |
+  <script>
+    window.location.href = "https://docmd.mgks.dev/content/containers/";
+    document.addEventListener("DOMContentLoaded", function () {
+        window.location.href = "https://docmd.mgks.dev/content/containers/";
+    });
+  </script>
+bodyClass: "no-style-example"
+---
+
+<div class="container">
+    Redirecting...<br/>
+    /custom-containers have moved to /containers now <a href="https://docmd.mgks.dev/content/containers/">Visit New Custom Containers Page</a>
+</div> 

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

@@ -8,6 +8,8 @@ components:
   css: true
   theme: true
   scripts: true
+  mainScripts: true
+copyCode: true
 customHead: |
   <style>
     body {

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

@@ -17,7 +17,9 @@ docmd offers a "no-style" page format that gives you maximum flexibility to crea
 
 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.
+By default, a no-style page will render just your content with minimal HTML structure. **All components are disabled by default** and must be explicitly enabled via the `components` object in frontmatter.
+
+> **Note:** This behavior changed in v0.2.0. Previously, some components were enabled by default and had to be disabled. Now all components are opt-in only.
 
 ## HTML Support
 
@@ -36,7 +38,7 @@ description: "Welcome to my project"
 noStyle: true
 components:
   meta: true  # Include meta tags, title, description
-  css: false  # Don't include default CSS
+  # css: false  # Not needed - CSS is disabled by default
 ---
 
 <div style="text-align: center; padding: 50px;">
@@ -48,32 +50,35 @@ components:
 
 ## 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` |
+You can control exactly which components are included in your page by setting them to `true` in the `components` object. **All components are disabled by default** and must be explicitly enabled:
+
+| Component | Description | Required Setting |
+|-----------|-------------|------------------|
+| `meta` | Meta tags, title, description | `meta: true` |
+| `siteTitle` | Include site title after page title | `siteTitle: true` |
+| `favicon` | Include favicon | `favicon: true` |
+| `css` | Include main CSS | `css: true` |
+| `highlight` | Include syntax highlighting CSS | `highlight: true` |
+| `theme` | Include theme-specific CSS | `theme: true` |
+| `themeMode` | Include theme mode toggle functionality | `themeMode: true` |
+| `customCss` | Include custom CSS files from config | `customCss: true` |
+| `pluginStyles` | Include plugin-specific CSS | `pluginStyles: true` |
+| `pluginHeadScripts` | Include plugin scripts in head | `pluginHeadScripts: true` |
+| `layout` | Use main content layout (`true`, `'full'`, or `false`) | `layout: true` or `layout: 'full'` |
+| `sidebar` | Include sidebar | `sidebar: true` |
+| `header` | Include page header | `header: true` |
+| `pageTitle` | Include page title in header | `pageTitle: true` |
+| `footer` | Include page footer | `footer: true` |
+| `branding` | Include docmd branding in footer | `branding: true` |
+| `logo` | Include logo in sidebar | `logo: true` |
+| `navigation` | Include navigation in sidebar | `navigation: true` |
+| `themeToggle` | Include theme toggle button | `themeToggle: true` |
+| `toc` | Include table of contents | `toc: true` |
+| `scripts` | Enable script loading (required for other script components) | `scripts: true` |
+| `mainScripts` | Include main JavaScript (copy code, theme toggle, etc.) | `mainScripts: true` |
+| `lightbox` | Include image lightbox functionality | `lightbox: true` |
+| `customJs` | Include custom JS files from config | `customJs: true` |
+| `pluginBodyScripts` | Include plugin scripts at end of body | `pluginBodyScripts: true` |
 
 ## Layout Options
 
@@ -83,6 +88,22 @@ The `components.layout` property has three possible values:
 - `true`: Use the main content layout with optional header and footer
 - `'full'`: Same as `true`, a full layout with content area
 
+## Script Components
+
+Script components work in a hierarchical manner:
+
+1. **`scripts: true`** - Enables script loading (required for all other script components)
+2. **`mainScripts: true`** - Includes main JavaScript functionality (copy code, theme toggle, etc.)
+3. **`lightbox: true`** - Includes image lightbox functionality (requires `mainScripts: true`)
+
+**Example:**
+```yaml
+components:
+  scripts: true      # Enable script loading
+  mainScripts: true  # Include main JavaScript
+  lightbox: true     # Include lightbox (requires mainScripts)
+```
+
 ## Sidebar Option
 
 If you set `components.sidebar: true`, the sidebar will be included with optional logo, navigation, and theme toggle button.
@@ -124,12 +145,15 @@ components:
   favicon: true
   css: true
   theme: true
+  themeMode: true
   layout: true
   header: true
   pageTitle: true
   footer: true
   branding: true
   scripts: true
+  mainScripts: true
+  lightbox: true
 customHead: |
   <link href="https://fonts.googleapis.com/css2?family=Poppins:wght@400;600&display=swap" rel="stylesheet">
   <style>

package/docs/index.md

@@ -7,32 +7,51 @@ components:
   favicon: true
   css: false
   theme: false
+  themeMode: true
   scripts: false
+  mainScripts: false
+  lightbox: false
+seo:
+  ldJson:
+    "@context": "https://schema.org"
+    "@type": "SoftwareApplication"
+    name: "docmd"
+    operatingSystem: "Any"
+    applicationCategory: "DeveloperApplication"
+    url: "https://docmd.mgks.dev"
+    description: "docmd is a Node.js-powered static site generator for Markdown documentation. It features custom containers, multiple themes, and zero client-side bloat."
+    creator:
+      "@type": "Person"
+      name: "Ghazi"
+      sameAs:
+        - "https://github.com/mgks"
+        - "https://mgks.dev"
+    codeRepository: "https://github.com/mgks/docmd"
+    releaseNotes: "See GitHub Releases for changelog"
+    programmingLanguage: "Node.js"
+    installUrl: "https://www.npmjs.com/package/@mgks/docmd"
 customHead: |
-  <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
-    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 currentTheme = document.documentElement.getAttribute('data-theme');
       const newTheme = currentTheme === 'light' ? 'dark' : 'light';
-      document.body.setAttribute('data-theme', newTheme);
+      document.documentElement.setAttribute('data-theme', newTheme);
       localStorage.setItem('docmd-theme', newTheme);
     }
-
-    // Run on page load
-    document.addEventListener('DOMContentLoaded', initTheme);
+    
+    function copyToClipboard(text) {
+      navigator.clipboard.writeText(text).then(() => {
+        const button = event.target.closest('.copy-button');
+        const originalHTML = button.innerHTML;
+        button.innerHTML = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="20,6 9,17 4,12"></polyline></svg>';
+        button.style.color = '#10b981';
+        setTimeout(() => {
+          button.innerHTML = originalHTML;
+          button.style.color = '';
+        }, 2000);
+      });
+    }
   </script>
 ---
 
@@ -97,6 +116,18 @@ customHead: |
       </div>
     </div>
 
+    <div class="install-section">
+      <div class="install-code">
+        <pre><code>npm install @mgks/docmd</code></pre>
+        <button class="copy-button" onclick="copyToClipboard('npm install @mgks/docmd')" aria-label="Copy npm install command">
+          <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
+            <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>
+          </svg>
+        </button>
+      </div>
+    </div>
+
     <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>

package/docs/plugins/seo.md

@@ -36,46 +36,93 @@ module.exports = {
 
 ## Configuration Options
 
-All options for the `seo` plugin are optional. If an option is not provided, the plugin will attempt to use sensible defaults or derive values from page frontmatter or `config.siteTitle`.
-
-*   `defaultDescription` (String):
-    *   A fallback meta description used for pages that do not have a `description` specified in their YAML frontmatter.
-*   `openGraph` (Object): Configures [Open Graph](https://ogp.me/) meta tags, primarily used by Facebook, LinkedIn, Pinterest, etc.
-    *   `siteName` (String): The name of your website (e.g., "My Project Documentation"). If not provided, `config.siteTitle` is used.
-    *   `defaultImage` (String): Absolute path (from site root) to a default image for `og:image` when a page is shared, if the page itself doesn't specify an image in its frontmatter (e.g., via `image: /path/to/page-image.png` or `ogImage: ...`).
-    *   Other tags like `og:title`, `og:description`, `og:url`, and `og:type` are automatically generated based on page frontmatter and URL.
-*   `twitter` (Object): Configures [Twitter Card](https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards) meta tags.
-    *   `cardType` (String): The type of Twitter card. Common values: `'summary'`, `'summary_large_image'`. Defaults to `'summary'`.
-    *   `siteUsername` (String): The Twitter @username of the site/publisher (e.g., `@MyProjectAccount`).
-    *   `creatorUsername` (String): The default Twitter @username of the content creator. Can be overridden per page via frontmatter (e.g., `twitterCreator: @PageAuthorHandle`).
-    *   Twitter tags like `twitter:title`, `twitter:description`, and `twitter:image` are also derived from page frontmatter, similar to Open Graph tags.
+The options in `config.js` serve as site-wide defaults. For the best results, you should provide specific metadata for each page using frontmatter.
 
 ## Frontmatter for SEO
 
-For the best SEO results, provide specific metadata in each page's frontmatter. The `seo` plugin will prioritize these values.
+To control SEO on a per-page basis, add a nested `seo` object to your page's frontmatter. This keeps all SEO-related settings organized and prevents conflicts with other frontmatter keys.
 
 ```yaml
 ---
 title: "Advanced Widget Configuration"
-description: "A detailed guide on configuring advanced settings for the Super Widget, including performance tuning and security options."
-image: "/assets/images/widgets/super-widget-social.jpg" # Used for og:image and twitter:image
-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
+description: "A detailed guide on configuring advanced settings for the Super Widget."
+seo:
+  description: "A more specific SEO description for search engines, overriding the main description if needed."
+  image: "/assets/images/widgets/super-widget-social.jpg"
+  ogType: "article"
+  twitterCard: "summary_large_image"
+  twitterCreator: "@widgetMaster"
+  keywords: ["widget", "configuration", "advanced", "performance"]
+  permalink: "https://example.com/docs/widgets/advanced-configuration"
+  noindex: false
 ---
+```
+
+::: callout info Backward Compatibility
+For backward compatibility, the plugin will still recognize top-level SEO fields like `image`, `ogType`, etc. However, the nested `seo:` structure is the recommended approach.
+:::
+
+### Supported Frontmatter Fields
+
+All fields should be placed inside the `seo:` object.
+
+*   `description` (String): Overrides the main page description for SEO meta tags.
+*   `image` or `ogImage` (String): Path to an image for `og:image` and `twitter:image`.
+*   `ogType` (String): Overrides the default Open Graph type (e.g., `article`, `website`).
+*   `twitterCard` (String): Overrides the default Twitter card type for this page.
+*   `twitterCreator` (String): The Twitter @username of the page's author.
+*   `keywords` (Array of Strings or String): Keywords for the `<meta name="keywords">` tag.
+*   `permalink` or `canonicalUrl` (String): The canonical URL for the page.
+*   `noindex` (Boolean): If `true`, adds `<meta name="robots" content="noindex">` to discourage search engines from indexing this page.
+
+## Structured Data (LD+JSON)
 
-# Advanced Widget Configuration
-...
+The SEO plugin can generate [Structured Data](https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data) (LD+JSON), which can enable rich search results. This feature is enabled per-page in your frontmatter.
+
+### Enabling Structured Data
+
+To generate a default LD+JSON block, add `ldJson: true` inside your `seo` frontmatter object.
+
+```yaml
+---
+title: "My Article"
+description: "An article about something important."
+seo:
+  ldJson: true
+---
 ```
-Supported frontmatter fields that the `seo` plugin may look for:
-*   `title` (Used for `og:title`, `twitter:title`)
-*   `description` (Used for `<meta name="description">`, `og:description`, `twitter:description`)
-*   `image` or `ogImage` (Used for `og:image`, `twitter:image`)
-*   `ogType` (Overrides default `og:type`)
-*   `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.
+
+This generates a basic `Article` schema using your page's metadata.
+
+### Customizing Structured Data
+
+For more control, provide an object to `ldJson`. This object will be merged with the default data, allowing you to add or override any properties.
+
+**Example: Customizing schema type and adding an author**
+
+```yaml
+---
+title: "Advanced Widget Configuration"
+description: "A detailed guide on configuring advanced settings for the Super Widget."
+seo:
+  image: "/assets/images/widgets/super-widget-social.jpg"
+  ldJson:
+    "@type": "TechArticle"
+    author:
+      "@type": "Person"
+      name: "Jane Doe"
+      url: "https://example.com/authors/jane-doe"
+    datePublished: "2024-01-15"
+    review:
+      "@type": "Review"
+      reviewRating:
+        "@type": "Rating"
+        ratingValue: "5"
+        bestRating: "5"
+      author:
+        "@type": "Person"
+        name: "John Smith"
+---
+```
+
+In this example, the schema type is changed to `TechArticle`, and detailed `author`, `datePublished`, and `review` information is added, giving search engines a much richer understanding of your content.

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "@mgks/docmd",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Generate beautiful, lightweight static documentation sites directly from your Markdown files. Zero clutter, just content.",
   "main": "src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "require": "./src/index.js"
+    }
+  },
   "bin": {
     "docmd": "bin/docmd.js"
   },
@@ -35,14 +41,14 @@
   },
   "homepage": "https://github.com/mgks/docmd#readme",
   "dependencies": {
-    "chokidar": "^3.6.0",
-    "commander": "^12.0.0",
+    "chokidar": "^4.0.3",
+    "commander": "^14.0.0",
     "ejs": "^3.1.9",
-    "express": "^4.19.2",
+    "express": "^5.1.0",
     "fs-extra": "^11.2.0",
     "gray-matter": "^4.0.3",
     "highlight.js": "^11.11.1",
-    "lucide-static": "^0.508.0",
+    "lucide-static": "^0.535.0",
     "markdown-it-abbr": "^2.0.0",
     "markdown-it-attrs": "^4.3.1",
     "markdown-it-container": "^4.0.0",
@@ -52,8 +58,8 @@
     "ws": "^8.17.0"
   },
   "devDependencies": {
-    "eslint": "^8.57.0",
-    "eslint-config-prettier": "^9.1.0",
+    "eslint": "^9.32.0",
+    "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-node": "^11.1.0",
     "prettier": "^3.2.5"
   },