@mgks/docmd 0.1.0

package/docs/plugins/analytics.md

@@ -0,0 +1,76 @@
+---
+title: "Analytics Integration"
+description: "Integrate web analytics services like Google Analytics into your docmd site to track visitor traffic."
+---
+
+# Analytics Integration Plugin
+
+`docmd` allows you to easily integrate popular web analytics services into your documentation site using the built-in analytics plugin. This helps you understand your audience, track page views, and gather insights into how your documentation is being used.
+
+## Enabling Analytics Plugin
+
+You enable analytics by adding the analytics plugin and its configuration to the `plugins` object in your `config.js`.
+
+**Example:**
+
+```javascript
+// config.js
+module.exports = {
+  // ...
+  plugins: {
+    // Analytics plugin configuration
+    analytics: {
+      // For Google Analytics 4 (GA4)
+      googleV4: {
+        measurementId: 'G-XXXXXXXXXX' // Your GA4 Measurement ID
+      },
+      
+      // For Google Universal Analytics (Legacy)
+      // googleUA: {
+      //   trackingId: 'UA-XXXXXXXXX-Y' // Your Universal Analytics Tracking ID
+      // }
+    },
+    
+    // ... other plugins
+  },
+  // ...
+};
+```
+
+Choose the analytics service and version you want to use by configuring the appropriate section.
+
+## Available Analytics Options
+
+### Google Analytics 4 (GA4)
+
+* **Configuration Key:** `googleV4`
+* **Description:** Integrates the latest version of Google Analytics, GA4. This is the recommended version for new Google Analytics setups.
+* **Options:**
+  * `measurementId` (String, Required): Your Google Analytics 4 Measurement ID, which typically looks like `G-XXXXXXXXXX`.
+* **Action:** Injects the standard Google Analytics 4 `gtag.js` tracking snippet into your pages.
+
+### Google Universal Analytics (Legacy)
+
+* **Configuration Key:** `googleUA`
+* **Description:** Integrates the older version of Google Analytics, known as Universal Analytics (UA). Note that Google has sunset Universal Analytics as of July 2023.
+* **Options:**
+  * `trackingId` (String, Required): Your Google Universal Analytics Tracking ID, which typically looks like `UA-XXXXXXXXX-Y`.
+* **Action:** Injects the standard Google Universal Analytics `analytics.js` tracking snippet into your pages.
+
+## Important Considerations
+
+* **Choose One Google Analytics Version:** If using Google Analytics, configure *either* `googleUA` *or* `googleV4`, but not both for the same property, to avoid incorrect data collection.
+* **Privacy and Consent:**
+  * Be mindful of user privacy when implementing analytics.
+  * Clearly disclose your use of analytics (and any cookies set by them) in your site's privacy policy or a cookie consent banner if required by regulations in your target regions (e.g., GDPR, CCPA).
+  * Consider features like IP anonymization if your analytics provider offers them and it's appropriate for your privacy stance.
+* **Testing:** After enabling the analytics plugin and deploying your site, verify that data is being collected correctly in your analytics provider's dashboard. Use browser developer tools (Network tab) to check if the tracking script is loading.
+
+## Future Analytics Support
+
+`docmd` may add support for other privacy-focused or popular analytics providers in the future, such as:
+* Plausible Analytics
+* Fathom Analytics
+* Simple Analytics
+
+Check the latest `docmd` documentation or GitHub repository for updates on supported analytics integrations.

package/docs/plugins/index.md

@@ -0,0 +1,71 @@
+---
+title: "Using Plugins with docmd"
+description: "Extend docmd's functionality with built-in plugins."
+---
+
+# Extending docmd with Plugins
+
+`docmd` supports a plugin system to add extra features and integrations to your documentation site without bloating the core tool. Plugins can modify the build process, inject content into pages, or add site-wide functionalities.
+
+## Enabling Plugins
+
+You enable and configure plugins in your `config.js` file within the `plugins` object. Each plugin is configured using its key with a corresponding configuration object.
+
+```javascript
+// config.js
+module.exports = {
+  // ... other config ...
+  plugins: {
+    // SEO Plugin
+    seo: {
+      defaultDescription: 'Your site-wide meta description',
+      openGraph: {
+        defaultImage: '/assets/images/og-preview.png',
+      },
+    },
+    // Analytics Plugin
+    analytics: {
+      googleV4: {
+        measurementId: 'G-XXXXXXXXXX'
+      }
+    },
+    // Sitemap Plugin
+    sitemap: {
+      defaultChangefreq: 'weekly',
+      defaultPriority: 0.8
+    }
+  },
+  // ...
+};
+```
+
+## Core Plugins
+
+`docmd` ships with several core plugins that you can easily enable:
+
+* **[SEO & Meta Tags](/plugins/seo/):** Automatically generates common SEO-related meta tags (description, Open Graph, Twitter Cards).
+* **[Analytics Integration](/plugins/analytics/):** Easily add tracking snippets for popular web analytics services like Google Analytics.
+* **[Sitemap](/plugins/sitemap/):** Generates a sitemap.xml file for search engines to better discover and index your content.
+
+Click on the links above or see the sidebar for detailed configuration of each core plugin.
+
+## How Plugins Work
+
+Plugins in `docmd` hook into various parts of the build process:
+
+* They can add meta tags and scripts to the page head
+* They can inject content or scripts at the beginning or end of the page body
+* They can generate additional files in the output directory
+* They can modify the HTML output of pages
+
+All plugins are designed to be configurable through your `config.js` file, giving you control over their behavior.
+
+## Future Plugin Development
+
+The plugin system is designed with future extensibility in mind. As `docmd` evolves, we plan to:
+
+* Add more built-in plugins for common documentation needs
+* Create an API for developers to build custom plugins
+* Enable community contribution of third-party plugins
+
+For now, focus on utilizing the available core plugins to enhance your site's functionality.

package/docs/plugins/seo.md

@@ -0,0 +1,79 @@
+---
+title: "SEO & Meta Tags Plugin"
+description: "Configure Search Engine Optimization (SEO) meta tags to improve your docmd site's discoverability."
+---
+
+# SEO & Meta Tags Plugin (`seo`)
+
+The `seo` plugin automatically generates important meta tags in the `<head>` of your HTML pages. This helps search engines and social media platforms understand, index, and display your content more effectively.
+
+## Enabling the Plugin
+
+Add the `seo` plugin to the `plugins` object in your `config.js`:
+
+```javascript
+// config.js
+module.exports = {
+  // ...
+  plugins: {
+    seo: {
+      defaultDescription: 'Discover insightful articles and guides on Project X. Your go-to resource for learning and development.',
+      openGraph: {
+        // siteName: 'Project X Documentation', // Optional, defaults to config.siteTitle
+        defaultImage: '/assets/images/default-og-image.png', // Absolute path from site root
+      },
+      twitter: {
+        cardType: 'summary_large_image', // e.g., 'summary', 'summary_large_image'
+        // siteUsername: '@ProjectX_Docs', // Your site's Twitter handle
+        // creatorUsername: '@YourHandle' // Default author handle (override in frontmatter)
+      }
+    },
+    // ... other plugins
+  },
+  // ...
+};
+```
+
+## 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.
+
+## Frontmatter for SEO
+
+For the best SEO results, provide specific metadata in each page's frontmatter. The `seo` plugin will prioritize these values.
+
+```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
+---
+
+# Advanced Widget Configuration
+...
+```
+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.
+
+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

@@ -0,0 +1,88 @@
+---
+title: "Sitemap Plugin"
+description: "Automatically generate a sitemap.xml for your docmd site to improve search engine discoverability."
+---
+
+# Sitemap Plugin (`sitemap`)
+
+The `sitemap` plugin automatically generates a `sitemap.xml` file for your documentation site. This helps search engines discover, crawl, and index your content more effectively, which can improve your site's visibility in search results.
+
+## Enabling the Plugin
+
+Add the `sitemap` plugin to the `plugins` object in your `config.js`:
+
+```javascript
+// config.js
+module.exports = {
+  // ...
+  plugins: {
+    sitemap: {
+      defaultChangefreq: 'weekly',
+      defaultPriority: 0.8
+    },
+    // ... other plugins
+  },
+  // ...
+};
+```
+
+## Configuration Options
+
+All options for the `sitemap` plugin are optional. If an option is not provided, the plugin will use sensible defaults.
+
+* `defaultChangefreq` (String): 
+  * Specifies how frequently the content is likely to change
+  * Possible values: `'always'`, `'hourly'`, `'daily'`, `'weekly'`, `'monthly'`, `'yearly'`, `'never'`
+  * Default: `'weekly'`
+  
+* `defaultPriority` (Number): 
+  * Indicates the relative importance of a page in your site
+  * Value between 0.0 and 1.0
+  * Default: `0.8`
+
+## How It Works
+
+The sitemap plugin automatically:
+
+1. Scans all generated HTML pages during the build process
+2. Creates a `sitemap.xml` file in the root of your site output directory
+3. Includes all pages with their URLs, last modification dates, and configured priorities
+
+The plugin uses your `siteUrl` property from the config.js file to create absolute URLs, which is required for a valid sitemap. Make sure you have a `siteUrl` defined:
+
+```javascript
+module.exports = {
+  siteUrl: 'https://yourdomain.com', // No trailing slash
+  // ... other config
+};
+```
+
+## Overriding Per-Page Settings with Frontmatter
+
+You can override the default sitemap settings for individual pages by adding specific frontmatter properties:
+
+```yaml
+---
+title: "Important Page"
+description: "This is a very important page that changes frequently"
+sitemap:
+  changefreq: 'daily'
+  priority: 1.0
+---
+```
+
+## Excluding Pages from the Sitemap
+
+If you want to exclude specific pages from the sitemap, you can add the following to your frontmatter:
+
+```yaml
+---
+title: "Private Page"
+description: "This page should not appear in search engines"
+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. 

package/docs/theming/available-themes.md

@@ -0,0 +1,85 @@
+---
+title: "Available Themes"
+description: "An overview of the built-in themes provided by docmd."
+---
+
+# Available Themes
+
+`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',
+    // ...
+  },
+  // ...
+};
+```
+
+## 2. `sky` Theme
+
+*   **`theme.name: 'sky'`**
+*   **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.
+*   **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.
+
+## 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
+
+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/custom-css-js.md

@@ -0,0 +1,84 @@
+---
+title: "Custom CSS & JS"
+description: "Learn how to add your own custom CSS and JavaScript to your docmd site for advanced customization."
+---
+
+# Custom Styles & Scripts
+
+While `docmd` themes provide a solid foundation, you can further tailor the appearance and behavior of your site by injecting custom CSS and JavaScript files. This is configured in your `config.js` file.
+
+## Custom CSS
+
+You can add one or more custom CSS files using the `theme.customCss` array in your `config.js`.
+
+```javascript
+// config.js
+module.exports = {
+  // ...
+  theme: {
+    name: 'default',
+    // ...
+    customCss: [
+      '/assets/css/my-branding.css', // Path relative to your site's root
+      '/css/another-stylesheet.css'
+    ],
+  },
+  // ...
+};
+```
+
+**How it works:**
+*   Each string in the `customCss` array should be an absolute path from the root of your generated `site/` directory (e.g., if your file is `site/assets/css/my-branding.css`, the path is `/assets/css/my-branding.css`).
+*   These `<link rel="stylesheet">` tags will be added to the `<head>` of every page *after* the main theme CSS and `highlight.js` CSS. This allows your custom styles to override the default theme styles.
+*   You are responsible for ensuring these CSS files exist at the specified locations in your final `site/` output. Typically, you would:
+    1.  Create your custom CSS files (e.g., `my-branding.css`).
+    2.  Place them in a folder within your project (e.g., `my-project/static-assets/css/`).
+    3.  Ensure that this folder (or its contents) is copied to the correct location in your `site/` directory during `docmd`'s asset copying process. If `docmd` copies a top-level `assets/` folder from your source, place them there.
+
+**Use Cases for Custom CSS:**
+*   **Overriding CSS Variables:** The `default` theme uses CSS variables extensively. You can redefine these in your custom CSS.
+    ```css
+    /* my-branding.css */
+    :root { /* Light mode overrides */
+      --primary-color: #D65A31; /* Example: Change primary color */
+      --font-family-sans: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      --text-color: #222;
+    }
+
+    body[data-theme="dark"] { /* Dark mode overrides */
+      --primary-color: #E87A5A;
+      --bg-color: #121212;
+      --text-color: #ddd;
+    }
+    ```
+*   **Styling Custom Components:** Add styles for specific elements or components unique to your documentation.
+*   **Fine-tuning Layout:** Make minor adjustments to spacing, sizing, or layout elements.
+
+## Custom JavaScript
+
+You can add one or more custom JavaScript files using the top-level `customJs` array in your `config.js`.
+
+```javascript
+// config.js
+module.exports = {
+  // ...
+  customJs: [
+    '/assets/js/my-interactive-script.js', // Path relative to your site's root
+    '/js/third-party-integration.js'
+  ],
+  // ...
+};
+```
+
+**How it works:**
+*   Each string in the `customJs` array should be an absolute path from the root of your generated `site/` directory.
+*   These `<script src="..."></script>` tags will be added just before the closing `</body>` tag on every page. This ensures the DOM is loaded before your scripts run and is generally better for page performance.
+*   Similar to custom CSS, you are responsible for ensuring these JavaScript files exist at the specified locations in your final `site/` output.
+
+**Use Cases for Custom JS:**
+*   Adding interactive elements (e.g., custom modals, tabs not provided by `docmd`).
+*   Integrating third-party services or widgets.
+*   Performing custom DOM manipulations after the page loads.
+*   Adding simple analytics or tracking snippets if not using a built-in plugin.
+
+By using `customCss` and `customJs`, you have significant flexibility to extend and personalize your `docmd` site beyond the standard theming options.

package/docs/theming/icons.md

@@ -0,0 +1,93 @@
+---
+title: "Using Icons"
+description: "How to use Lucide icons in your docmd site navigation and content."
+---
+
+# Using Icons
+
+`docmd` allows you to add visual flair and improve navigation clarity with SVG icons from the [Lucide icon library](https://lucide.dev/).
+
+## Icons in Navigation
+
+You can specify an icon for each navigation item (including parent categories) in your `config.js` file using the `icon` property:
+
+```javascript
+// config.js
+// ...
+navigation: [
+  { title: 'Home', path: '/', icon: 'home' },
+  {
+    title: 'User Guides',
+    icon: 'book-open', // Icon for the category
+    children: [
+      { title: 'Installation', path: '/user-guides/installation', icon: 'download' },
+      { title: 'First Steps', path: '/user-guides/first-steps', icon: 'footprints' },
+    ]
+  },
+  { title: 'API Reference', path: '/api-reference', icon: 'code' }
+]
+// ...
+```
+
+**How it Works:**
+* The `icon` value (e.g., `'home'`, `'book-open'`) uses kebab-case notation that maps to Lucide icon names.
+* During build, `docmd` converts these names to the appropriate Lucide icon SVGs.
+* The navigation template renders these icons inline for optimal performance.
+
+## Available Icons
+
+`docmd` uses the [Lucide](https://lucide.dev/) icon library, which provides a comprehensive set of beautiful, consistent open-source icons.
+
+To see all available icons and their names:
+1. Visit the [Lucide Icons Gallery](https://lucide.dev/icons/)
+2. When you find an icon you want to use, note its name (shown below each icon)
+3. Use the kebab-case version of the name in your config (e.g., `arrow-up-right` instead of `ArrowUpRight`)
+
+**Common Icon Examples:**
+* Navigation: `home`, `book-open`, `file-text`, `settings`, `users`
+* Actions: `download`, `upload-cloud`, `play`, `external-link`
+* UI Elements: `sun`, `moon`, `menu`, `x`, `search`
+* Indicators: `alert-circle`, `check-circle`, `info`
+* Directional: `chevron-right`, `chevron-down`, `arrow-left`
+
+## Icon Styling
+
+Lucide icons in `docmd` are styled using CSS. They are rendered as inline SVGs with appropriate classes for targeting:
+
+```css
+/* Example styling for navigation icons */
+.sidebar-nav .lucide-icon {
+  width: 1.2em;
+  height: 1.2em;
+  margin-right: 0.5em;
+  vertical-align: middle;
+  stroke-width: 2px; /* Adjust line thickness */
+  stroke: currentColor; /* Use current text color */
+}
+
+/* Example of targeting a specific icon */
+.sidebar-nav .icon-home {
+  color: #3498db; /* Blue color for home icon */
+}
+```
+
+The icons have the following CSS classes you can target:
+- `.lucide-icon` - Applied to all Lucide icons
+- `.icon-{name}` - Applied to specific icons, e.g., `.icon-home`
+
+You can add these styles to your custom CSS file specified in `theme.customCss` in your configuration.
+
+## Using Icons in Content
+
+To use icons directly in your Markdown content, you'll need to use HTML with inline SVGs. You can copy SVG code directly from the [Lucide website](https://lucide.dev/) and paste it into your Markdown.
+
+```html
+<!-- Example of inline SVG in Markdown -->
+<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-info">
+  <circle cx="12" cy="12" r="10"></circle>
+  <path d="M12 16v-4"></path>
+  <path d="M12 8h.01"></path>
+</svg> This is a note with an info icon.
+```
+
+A future version of `docmd` might provide shortcodes or other simplified ways to use icons directly in Markdown content.

package/docs/theming/index.md

@@ -0,0 +1,19 @@
+---
+title: "Theming Your docmd Site"
+description: "Learn how to customize the appearance of your docmd site, including themes, modes, custom styles, and icons."
+---
+
+# Theming Your docmd Site
+
+`docmd` allows for extensive customization of your documentation site's appearance, ensuring it aligns with your branding and provides an optimal user experience.
+
+## Core Theming Concepts:
+
+*   **[Available Themes](/theming/available-themes/):** Choose from pre-built themes to quickly change the overall look and feel.
+*   **[Light & Dark Mode](/theming/light-dark-mode/):** Understand how to set the default color mode and enable user toggling.
+*   **[Custom CSS & JS](/theming/custom-css-js/):** Inject your own CSS and JavaScript files for fine-grained control over styling and functionality.
+*   **[Using Icons](/theming/icons/):** Enhance navigation and content with SVG icons.
+*   **CSS Variables:** The default theme (`default`) is built using CSS variables, making it easier to tweak common properties like colors and fonts via your custom CSS.
+*   **Syntax Highlighting:** Code block themes are provided for both light and dark modes via `highlight.js` stylesheets, adapting to the current color mode.
+
+The goal is to provide a good-looking, accessible site out-of-the-box, with straightforward ways to adapt it to your specific needs.