@mgks/docmd 0.2.9 → 0.3.0

package/README.md

@@ -28,7 +28,7 @@
 <br>
 
 <p align="center">
-  <img width="2856" height="1558" alt="519536477-8d948e18-8e2d-420d-8902-96e1aafab1ba-modified" src="https://github.com/user-attachments/assets/5b883c80-8357-46e8-9adb-84e38a0da64c" />
+  <img width="2856" height="1558" alt="519536477-8d948e18-8e2d-420d-8902-96e1aafab1ba-modified" src="https://docmd.mgks.dev/assets/images/preview-dark-welcome.png" />
   <sup><i>docmd noStyle page preview in dark mode</i></sup>
 </p>
 
@@ -39,6 +39,7 @@ Most documentation tools today are too heavy (React hydration, massive bundles)
 **docmd** fills the gap. It is a native Node.js tool that generates **pure, static HTML**.
 
 *   ⚡ **Blazing Fast:** No hydration delay. Instant page loads.
+*   🔍 **Offline Search:** Powerful full-text search included automatically.
 *   🛠 **Zero Config:** Works out of the box with sensible defaults.
 *   🎨 **Theming:** Built-in light/dark modes and multiple themes (`sky`, `ruby`, `retro`).
 *   📦 **Node.js Native:** No Python, no Gemfiles. Just `npm install`.
@@ -92,6 +93,7 @@ Live reload is active. Browser will refresh automatically when files change.
 | **Markdown First** | Standard Markdown + Frontmatter. No proprietary syntax to learn. |
 | **Smart CLI** | Intelligent config validation catches typos before they break your build. |
 | **Custom Containers** | Use `::: callout`, `::: card`, `::: steps`, `::: tabs`, `::: collapsible`, `::: changelog`, and more to enrich content. |
+| **Smart Search** | Built-in, offline-capable full-text search with fuzzy matching and highlighting. No API keys required. |
 | **Diagrams** | Create flowcharts, relationship diagrams, journey, piecharts, graphs, timelines and more with Mermaid. |
 | **No-Style Pages** | Create custom landing pages (highly customizable custom HTML pages) without theme constraints. |
 | **Auto Dark Mode** | Respects system preference and saves user choice. |

package/config.js

@@ -1,207 +1,175 @@
 // Source file from the docmd project — https://github.com/mgks/docmd
 
-// Configuration for the docmd project's own documentation
 module.exports = {
-  // Core Site Metadata
+  // --- Core Metadata ---
   siteTitle: 'docmd',
-  // Define a base URL for your site, crucial for SEO and absolute paths
-  // No trailing slash
-  siteUrl: 'https://docmd.mgks.dev', // Replace with your actual deployed URL
+  siteUrl: 'https://docmd.mgks.dev', // No trailing slash
 
-  // Logo Configuration
+  // --- Branding ---
   logo: {
-    light: '/assets/images/docmd-logo-light.png', // Path relative to outputDir root
-    dark: '/assets/images/docmd-logo-dark.png',   // Path relative to outputDir root
-    alt: 'docmd Logo',                      // Alt text for the logo
-    href: '/',                              // Link for the logo, defaults to site root
+    light: '/assets/images/docmd-logo-light.png',
+    dark: '/assets/images/docmd-logo-dark.png',
+    alt: 'docmd Logo',
+    href: '/',
   },
+  favicon: '/assets/favicon.ico',
+
+  // --- Structure ---
+  srcDir: 'docs',       // Source markdown files directory
+  outputDir: 'site',    // Output directory for generated site
 
-  // Directory Configuration
-  srcDir: 'docs',       // Source directory for Markdown files
-  outputDir: 'site',    // Directory for generated static site
-  minify: true,         // Enable/disable HTML/CSS/JS minification
+  // --- Features & UX ---
+  search: true,           // Built-in offline search
+  minify: true,           // Production build optimization
+  autoTitleFromH1: true,  // Auto-generate title from first H1 if frontmatter title is missing
+  copyCode: true,         // Enable "copy to clipboard" on code blocks
+  pageNavigation: true,   // Next/Prev links
 
-  // Sidebar Configuration
+  // --- Sidebar & Theme ---
   sidebar: {
-    collapsible: true,        // or false to disable
-    defaultCollapsed: false,  // or true to start collapsed
+    collapsible: true,
+    defaultCollapsed: false,
   },
-
-  // Theme Configuration
   theme: {
-    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
-    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
-    ],
+    name: 'sky',            // 'default', 'sky', 'ruby', 'retro'
+    defaultMode: 'light',   // 'light' or 'dark'
+    enableModeToggle: true, // Show theme mode toggle button 
+    positionMode: 'top',    // 'top' or 'bottom' of header
+    codeHighlight: true,    // Enable code syntax highlighting
+    customCss: [],          // Add paths relative to outputDir here
   },
-
-  // Custom JavaScript Files
-  customJs: [               // Array of paths to custom JS files, loaded at end of body
-     '/assets/js/docmd-image-lightbox.js', // Image lightbox functionality
+  customJs: [
+    '/assets/js/docmd-image-lightbox.js',
   ],
 
-  // 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 ---
   plugins: {
-    // SEO Plugin Configuration
-    // 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.',
-      openGraph: { // For Facebook, LinkedIn, etc.
-        // siteName: 'docmd Documentation', // Optional, defaults to config.siteTitle
-        // Default image for `og:image` if not specified in page frontmatter
-        // Path relative to outputDir root
+      defaultDescription: 'The minimalist, zero-config documentation generator for Node.js developers.',
+      openGraph: {
         defaultImage: '/assets/images/docmd-preview.png',
       },
-      twitter: { // For Twitter Cards
-        cardType: 'summary_large_image', // 'summary', 'summary_large_image'
-        // siteUsername: '@docmd_handle',    // Your site's Twitter handle (optional)
-        // creatorUsername: '@your_handle', // Default author handle (optional, can be overridden in frontmatter)
+      twitter: {
+        cardType: 'summary_large_image',
       }
     },
-    // Analytics Plugin Configuration
     analytics: {
-      // Google Analytics 4 (GA4)
       googleV4: {
-        measurementId: 'G-8QVBDQ4KM1' // Replace with your actual GA4 Measurement ID
-      },
-      // Google Universal Analytics (UA) - Legacy (optional)
-      // googleUA: {
-      //   trackingId: 'UA-XXXXXXXXX-Y' // Replace with your actual UA Tracking ID
-      // }
+        measurementId: 'G-8QVBDQ4KM1'
+      }
     },
-    // Enable Sitemap plugin
     sitemap: {
       defaultChangefreq: 'weekly',
       defaultPriority: 0.8
     }
-    // Add other future plugin configurations here by their key
   },
 
-  // "Edit this page" Link Configuration
+  // --- Doc Source Link ---
   editLink: {
     enabled: true,
-    // The URL to the folder containing your docs in the git repo
-    // Note: It usually ends with /edit/main/docs or /blob/main/docs
     baseUrl: 'https://github.com/mgks/docmd/edit/main/docs',
     text: 'Edit this page on GitHub'
   },
 
-  // Navigation Structure (Sidebar)
-  // Icons are kebab-case names from Lucide Icons (https://lucide.dev/)
+  // --- Navigation ---
   navigation: [
-      { title: 'Welcome', path: '/', icon: 'feather' },
-      { title: 'Overview', path: '/overview', icon: 'home' },
-      // { title: 'Support the Project', path: 'https://github.com/sponsors/mgks', icon: 'heart', external: true },
-      {
-        title: 'Getting Started',
-        icon: 'rocket',
-        path: '/getting-started/',
-        children: [
-          { title: 'Installation', path: '/getting-started/installation', icon: 'download' },
-          { title: 'Basic Usage', path: '/getting-started/basic-usage', icon: 'play' },
-        ],
-      },
-      { title: 'Configuration', path: '/configuration', icon: 'settings' },
-      {
-        title: 'Content',
-        icon: 'layout-template',
-        path: '/content/',
-        collapsible: true,
-        children: [
-          { title: 'Frontmatter', path: '/content/frontmatter', icon: 'file-text' },
-          { title: 'Markdown Syntax', path: '/content/markdown-syntax', icon: 'code-2' },
-          { title: 'Images', path: '/content/images', icon: 'image' },
-          { title: 'Mermaid Diagrams', path: '/content/mermaid', icon: 'network' },
-          {
-            title: 'Custom Containers',
-            path: '/content/containers/',
-            icon: 'box',
-            collapsible: true,
-            children: [
-              { title: 'Callouts', path: '/content/containers/callouts', icon: 'megaphone' },
-              { title: 'Cards', path: '/content/containers/cards', icon: 'panel-top' },
-              { title: 'Steps', path: '/content/containers/steps', icon: 'list-ordered' },
-              { title: 'Tabs', path: '/content/containers/tabs', icon: 'columns-3' },
-              { title: 'Collapsible', path: '/content/containers/collapsible', icon: 'chevrons-down' },
-              { title: 'Changelogs', path: '/content/containers/changelogs', icon: 'logs' },
-              { title: 'Buttons', path: '/content/containers/buttons', icon: 'mouse-pointer-click' },
-              { title: 'Nested Containers', path: '/content/containers/nested-containers', icon: 'folder-tree' },
-            ]
-          },
-          { title: 'No-Style Pages', path: '/content/no-style-pages', icon: 'layout' },
-          { title: 'No-Style Example', path: '/content/no-style-example', icon: 'sparkles' },
-        ],
-      },
-      {
-        title: 'Theming',
-        icon: 'palette',
-        path: '/theming/',
-        collapsible: true,
-        children: [
-          { title: 'Available Themes', path: '/theming/available-themes', icon: 'layout-grid' },
-          { title: 'Light & Dark Mode', path: '/theming/light-dark-mode', icon: 'sun-moon' },
-          { title: 'Custom CSS & JS', path: '/theming/custom-css-js', icon: 'file-code' },
-          { title: 'Icons', path: '/theming/icons', icon: 'pencil-ruler' },
-        ],
-      },
-      {
-        title: 'Plugins',
-        icon: 'puzzle',
-        path: '/plugins/',
-        collapsible: true,
-        children: [
-          { title: 'SEO & Meta Tags', path: '/plugins/seo', icon: 'search' },
-          { title: 'Analytics', path: '/plugins/analytics', icon: 'bar-chart' },
-          { title: 'Sitemap', path: '/plugins/sitemap', icon: 'map' },
-        ],
-      },
-      {
-        title: 'Recipes',
-        icon: 'chef-hat',
-        path: '/recipes/',
-        collapsible: true,
-        children: [
-          { title: 'Landing Page', path: '/recipes/landing-page', icon: 'panel-top' },
-          { title: 'Custom Fonts', path: '/recipes/custom-fonts', icon: 'type-outline' },
-          { title: 'Favicon', path: '/recipes/favicon', icon: 'circle-dashed' },
-        ],
-      },
-      { title: 'CLI Commands', path: '/cli-commands', icon: 'terminal' },
-      { title: 'Deployment', path: '/deployment', icon: 'upload-cloud' },
-      { title: 'Contributing', path: '/contributing', icon: 'users-2' },
-      { title: 'Comparison', path: '/comparison', icon: 'shapes' },
-
-      { title: 'GitHub', path: 'https://github.com/mgks/docmd', icon: 'github', external: true },
-      { title: 'Discussions', path: 'https://github.com/mgks/docmd/discussions', icon: 'message-square', external: true },
-      { title: 'Issues', path: 'https://github.com/mgks/docmd/issues', icon: 'badge-alert', external: true }
-  ],
+    { title: 'Welcome', path: '/', icon: 'feather' },
+    { title: 'Overview', path: '/overview', icon: 'home' },
 
-  pageNavigation: true, // Enable previous / next page navigation at the bottom of each page
+    {
+      title: 'Getting Started',
+      icon: 'rocket',
+      path: '/getting-started/',
+      children: [
+        { title: 'Installation', path: '/getting-started/installation', icon: 'download' },
+        { title: 'Basic Usage', path: '/getting-started/basic-usage', icon: 'play' },
+      ],
+    },
 
-  // Sponsor Ribbon Configuration
-  sponsor: {
-    enabled: true,                    // Enable/disable the sponsor ribbon
-    title: 'Sponsor',     // Text to display on the ribbon
-    link: 'https://github.com/sponsors/mgks', // URL for the sponsor link
-  },
+    { title: 'Configuration', path: '/configuration', icon: 'settings' },
 
-  // Footer Configuration
-  // Markdown is supported here.
-  footer: '© ' + new Date().getFullYear() + ' Project docmd.',
+    {
+      title: 'Content',
+      icon: 'layout-template',
+      path: '/content/',
+      collapsible: true,
+      children: [
+        { title: 'Markdown Syntax', path: '/content/markdown-syntax', icon: 'code-2' },
+        { title: 'Frontmatter', path: '/content/frontmatter', icon: 'file-text' },
+        { title: 'Images & Lightbox', path: '/content/images', icon: 'image' },
+        { title: 'Search', path: '/content/search', icon: 'search' },
+        { title: 'Mermaid Diagrams', path: '/content/mermaid', icon: 'network' },
+        {
+          title: 'Containers',
+          path: '/content/containers/',
+          icon: 'box',
+          collapsible: true,
+          children: [
+            { title: 'Callouts', path: '/content/containers/callouts', icon: 'megaphone' },
+            { title: 'Cards', path: '/content/containers/cards', icon: 'panel-top' },
+            { title: 'Steps', path: '/content/containers/steps', icon: 'list-ordered' },
+            { title: 'Tabs', path: '/content/containers/tabs', icon: 'columns-3' },
+            { title: 'Collapsible', path: '/content/containers/collapsible', icon: 'chevrons-down' },
+            { title: 'Changelogs', path: '/content/containers/changelogs', icon: 'history' },
+            { title: 'Buttons', path: '/content/containers/buttons', icon: 'mouse-pointer-click' },
+            { title: 'Nested Containers', path: '/content/containers/nested-containers', icon: 'folder-tree' },
+          ]
+        },
+        { title: 'No-Style Pages', path: '/content/no-style-pages', icon: 'layout' },
+      ],
+    },
 
-  // Favicon Configuration
-  // Path relative to outputDir root
-  favicon: '/assets/favicon.ico',
+    {
+      title: 'Theming',
+      icon: 'palette',
+      path: '/theming/',
+      collapsible: true,
+      children: [
+        { title: 'Available Themes', path: '/theming/available-themes', icon: 'layout-grid' },
+        { title: 'Light & Dark Mode', path: '/theming/light-dark-mode', icon: 'sun-moon' },
+        { title: 'Custom CSS & JS', path: '/theming/custom-css-js', icon: 'file-code' },
+        { title: 'Icons', path: '/theming/icons', icon: 'pencil-ruler' },
+      ],
+    },
+
+    {
+      title: 'Plugins',
+      icon: 'puzzle',
+      path: '/plugins/',
+      collapsible: true,
+      children: [
+        { title: 'SEO & Meta', path: '/plugins/seo', icon: 'search' },
+        { title: 'Analytics', path: '/plugins/analytics', icon: 'bar-chart' },
+        { title: 'Sitemap', path: '/plugins/sitemap', icon: 'map' },
+      ],
+    },
+
+    {
+      title: 'Recipes',
+      icon: 'chef-hat',
+      path: '/recipes/',
+      collapsible: true,
+      children: [
+        { title: 'Landing Page', path: '/recipes/landing-page', icon: 'layout-template' },
+        { title: 'Custom Fonts', path: '/recipes/custom-fonts', icon: 'type' },
+        { title: 'Favicon', path: '/recipes/favicon', icon: 'image-plus' },
+      ],
+    },
+
+    { title: 'CLI Commands', path: '/cli-commands', icon: 'terminal' },
+    { title: 'Deployment', path: '/deployment', icon: 'upload-cloud' },
+    { title: 'Comparison', path: '/comparison', icon: 'scale' },
+    { title: 'Contributing', path: '/contributing', icon: 'git-pull-request' },
+
+    { title: 'GitHub', path: 'https://github.com/mgks/docmd', icon: 'github', external: true },
+    { title: 'Discussions', path: 'https://github.com/mgks/docmd/discussions', icon: 'message-circle', external: true },
+  ],
+
+  // --- Footer & Sponsor ---
+  footer: '© ' + new Date().getFullYear() + ' Project docmd.',
+  sponsor: {
+    enabled: true,
+    title: 'Sponsor',
+    link: 'https://github.com/sponsors/mgks',
+  },
 };

package/docs/comparison.md

@@ -16,12 +16,17 @@ Choosing the right tool depends on your specific needs. `docmd` was built to fil
 | **Setup Time** | ~2 minutes | ~15 minutes | ~10 mins (Python env) | Instant (SaaS) | Instant |
 | **Client JS Size** | **Tiny (< 15kb)** | Heavy (React Bundle) | Minimal | Medium | Medium |
 | **Customization** | Standard CSS/JS | React Components | Python/Jinja2 | JSON Config | Vue/Plugins |
+| **Search** | **Built-in (Offline)** | Algolia (Requires Setup) | Built-in (Lunr) | Built-in | Client-side Plugin |
 | **SEO** | **Excellent** | Excellent | Excellent | Excellent | **Poor** |
 | **Hosting** | **Anywhere** | Anywhere | Anywhere | **Vendor Locked** | Anywhere |
 | **Cost** | **100% Free OSS** | 100% Free OSS | 100% Free OSS | Freemium | 100% Free OSS |
 
 ## Detailed Breakdown
 
+### The Search Advantage
+*   **Docusaurus and others** rely on 3rd party services like Algolia and others. This is great for enterprise scale, but for most projects, it's a hassle. You have to apply for an account, manage API keys, and configure crawlers.
+*   **docmd** includes a production-grade search engine out of the box. It generates a local index during the build. This means your documentation is **searchable even offline** (perfect for Intranets or air-gapped networks) and respects user privacy completely.
+
 ### vs. Docusaurus
 **Docusaurus** is the gold standard for large-scale React projects (like Meta's own docs).
 *   **Choose Docusaurus if:** You need to embed complex React components inside your markdown, need versioning *today*, or are building a massive site with thousands of pages.

package/docs/configuration.md

@@ -22,6 +22,8 @@ module.exports = {
   srcDir: 'docs',
   outputDir: 'site',
 
+  search: true,
+
   sidebar: {
     collapsible: true,
     defaultCollapsed: false,
@@ -125,13 +127,17 @@ module.exports = {
 *   **Default:** `'site'`
 *   **Description:** Directory where the static site will be generated.
 
+### `search`
+*   **Type:** `Boolean`
+*   **Default:** `true`
+*   **Description:** Controls the visibility of the full-text search bar in the header and the generation of the search index. Set to `false` to disable search capabilities entirely.
+
 ## `minify`
 *   **Type:** `Boolean`
 *   **Optional**
 *   **Default:** `true` when running `docmd build`, `false` when running `docmd dev`.
 *   **Description:** Controls whether CSS and JavaScript assets are minified (compressed) during the build.
 *   **Usage:** You can force this to `false` if you need to debug production builds.
-*   **Example:** `minify: false`
 
 ### `autoTitleFromH1`
 *   **Type:** `Boolean`

package/docs/content/search.md

@@ -0,0 +1,68 @@
+---
+title: "Full-Text Search"
+description: "How to use and configure the built-in, offline-capable search engine in docmd."
+---
+
+# Full-Text Search
+
+`docmd` comes with a powerful, built-in full-text search engine. It requires **zero configuration**, works completely **offline**, and provides instant results with keyword highlighting.
+
+## How It Works
+
+Unlike other documentation tools that rely on external services (like Algolia) or heavy server-side indexing, `docmd` takes a modern, lightweight approach:
+
+1.  **Build Time:** During `docmd build`, the system scans all your markdown files. It strips HTML tags, extracts headings, and compiles a highly optimized `search-index.json`.
+2.  **Client Side:** When a user visits your site, a lightweight search library (MiniSearch) is loaded.
+3.  **Instant Querying:** Searching happens entirely in the user's browser. There is no network latency, no API limits, and no tracking.
+
+## Features
+
+*   **Fuzzy Matching:** Finds results even if there are typos (e.g., "installation" matches "instalation").
+*   **Smart Snippets:** Shows the exact context of the keyword in the search results, with the matching terms highlighted.
+*   **Keyboard Navigation:** Full support for `ArrowUp`, `ArrowDown`, and `Enter`.
+*   **Shortcuts:** Press `Cmd + K` (Mac) or `Ctrl + K` (Windows/Linux) to open anywhere.
+*   **Offline Capable:** Once the page loads, search works without an internet connection.
+
+## Configuration
+
+Search is **enabled by default**. You don't need to do anything to get started.
+
+### Disabling Search
+If you prefer to hide the search bar, set `search: false` in your config:
+
+```javascript
+// docmd.config.js
+module.exports = {
+  // ...
+  search: false, 
+  // ...
+};
+```
+
+### Excluding Pages
+Sometimes you have utility pages or draft content you don't want appearing in search results. You can exclude specific pages using frontmatter:
+
+```yaml
+---
+title: "Private Draft"
+noindex: true
+---
+```
+
+Using `noindex: true` does two things:
+1.  Removes the page from the internal **Search Index**.
+2.  Adds a `<meta name="robots" content="noindex">` tag to prevent Google/Bing indexing.
+
+## Comparison vs. Algolia
+
+Many documentation generators (like Docusaurus) rely on **Algolia DocSearch**. While Algolia is powerful, it introduces friction:
+
+| Feature | docmd Search | Algolia / External |
+| :--- | :--- | :--- |
+| **Setup** | **Zero Config** (Automatic) | Complex (API Keys, CI/CD crawling) |
+| **Privacy** | **100% Private** (Client-side) | Data sent to 3rd party servers |
+| **Offline** | **Yes** | No |
+| **Cost** | **Free** | Free tier limits or Paid |
+| **Speed** | **Instant** (In-memory) | Fast (Network latency dependent) |
+
+`docmd` creates a frictionless experience: you write Markdown, we handle the discovery.

package/docs/overview.md

@@ -30,6 +30,7 @@ This very documentation site is built using `docmd`!
 ## Key Features
 
 *   📝 **Standard Markdown & Frontmatter:** Write content naturally, define page metadata (title, description) easily.
+*   🔍 **Smart Search:** Built-in, offline-capable full-text search with fuzzy matching and highlighting. No API keys required.
 *   🎨 **Themeable:** Built-in light/dark modes, customizable via CSS variables. Uses `highlight.js` for code blocks.
 *   🧩 **Custom Containers:** Add richer components like callouts, cards, and steps using simple `::: name :::` syntax.
 *   ⚙️ **Config-Driven Navigation:** Define your site structure and sidebar navigation in `docmd.config.js`. Supports nested items.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mgks/docmd",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "Generate beautiful, lightweight static documentation sites directly from your Markdown files. Zero clutter, just content.",
   "main": "src/index.js",
   "exports": {
@@ -59,6 +59,9 @@
     "markdown-it-deflist": "^3.0.0",
     "markdown-it-footnote": "^4.0.0",
     "markdown-it-task-lists": "^2.1.1",
+    "mermaid": "^11.12.1",
+    "minisearch": "^7.2.0",
+    "striptags": "^3.2.0",
     "ws": "^8.17.0"
   },
   "devDependencies": {
@@ -70,4 +73,4 @@
   "directories": {
     "doc": "docs"
   }
-}
+}