@mgks/docmd 0.1.4 → 0.2.1

package/docs/index.md

@@ -7,35 +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="preconnect" href="https://fonts.googleapis.com">
-  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=PT+Mono:wght@700&display=swap" rel="stylesheet">
   <link rel="stylesheet" href="/assets/css/welcome.css">
   <script>
-    // Initialize theme from localStorage or system preference
-    function initTheme() {
-      const storedTheme = localStorage.getItem('docmd-theme');
-      if (storedTheme) {
-        document.body.setAttribute('data-theme', storedTheme);
-      } else {
-        const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
-        document.body.setAttribute('data-theme', prefersDark ? 'dark' : 'light');
-      }
-    }
-
-    // Toggle theme between light and dark
     function toggleTheme() {
-      const currentTheme = document.body.getAttribute('data-theme');
+      const 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>
 ---
 
@@ -100,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>
@@ -124,16 +152,16 @@ customHead: |
   <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>

package/docs/plugins/seo.md

@@ -36,44 +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
+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.
-
-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/docs/theming/available-themes.md

@@ -12,8 +12,8 @@ description: "An overview of the built-in themes provided by docmd."
 module.exports = {
   // ...
   theme: {
-    name: 'theme-name', // Options: 'default', 'sky', 'ruby'
-    defaultMode: 'light', // or 'dark'
+    name: 'theme-name', // Options: 'default', 'sky', 'ruby', 'retro'
+    defaultMode: 'light', // or 'dark' to set as landing mode
     // ...
   },
   // ...
@@ -52,6 +52,20 @@ module.exports = {
     *   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:
@@ -59,5 +73,6 @@ Each theme consists of CSS files located within `docmd`'s internal assets. When
 - `default` theme uses the base CSS with no additional theme stylesheet
 - `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,16 @@
 {
   "name": "@mgks/docmd",
-  "version": "0.1.4",
+  "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"
+    "docmd": "bin/docmd.js"
   },
   "scripts": {
     "start": "node ./bin/docmd.js dev",
@@ -35,23 +41,29 @@
   },
   "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",
-    "markdown-it": "^14.1.0",
+    "lucide-static": "^0.535.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": {
-    "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"
+  },
+  "directories": {
+    "doc": "docs"
   }
 }