@mgks/docmd 0.3.1 → 0.3.3

package/docs/cli-commands.md

@@ -1,108 +0,0 @@
----
-title: "CLI Commands"
-description: "A reference guide to all available docmd command-line interface (CLI) commands and their options."
----
-
-# CLI Commands
-
-`docmd` provides a set of commands to help you initialize, build, and preview your documentation site.
-
-## `docmd init`
-
-Initializes a new `docmd` project in the current directory.
-
-**Usage:**
-```bash
-docmd init
-```
-
-**Description:**
-This command creates the basic file and directory structure required for a `docmd` project:
-*   `docs/`: A directory to store your Markdown source files.
-    *   `docs/index.md`: A sample Markdown file.
-*   `docmd.config.js`: The main configuration file for your site, pre-filled with default settings.
-
-If a `docs/` directory or `docmd.config.js` file already exists, `docmd init` will typically warn you and avoid overwriting them to prevent accidental data loss.
-
-**Options:**
-This command currently does not take any options.
-
-## `docmd build`
-
-Builds your static documentation site.
-
-**Usage:**
-```bash
-docmd build [options]
-```
-
-**Description:**
-The `build` command reads your Markdown files from the source directory (specified by `srcDir` in `docmd.config.js`, defaults to `docs/`), processes them along with your `docmd.config.js`, and generates a complete static website in the output directory (specified by `outputDir` in `docmd.config.js`, defaults to `site/`).
-
-The output `site/` directory contains all the HTML, CSS, JavaScript, and other assets needed to deploy your documentation.
-
-By default, the build process will update all assets to ensure you have the latest versions from the docmd package. This ensures your site benefits from the latest improvements and fixes.
-
-**Options:**
-
-*   `-c, --config <path>`
-    *   **Default:** `docmd.config.js` or `config.js`
-    *   **Description:** Specifies the path to the configuration file.
-
-*   `-p, --preserve`
-    *   **Default:** `false`
-    *   **Description:** Preserves existing asset files instead of updating them.
-
-*   `--silent`
-    *   **Default:** `false`
-    *   **Description:** Suppresses most log output in the console. Useful for running in automated environments.
-
-## `docmd dev`
-
-Starts a local development server with live reloading.
-
-**Usage:**
-```bash
-docmd dev [options]
-```
-
-**Description:**
-The `dev` command is essential for writing and previewing your documentation. It:
-1.  Performs an initial build of your site.
-2.  Starts a local web server (usually on `http://localhost:3000`).
-3.  Watches your source files (`docs/` directory, `docmd.config.js`, and internal `docmd` theme assets) for changes.
-4.  When a change is detected, it automatically rebuilds the necessary parts of your site and triggers a live reload in your browser.
-
-This provides a fast feedback loop, allowing you to see your changes almost instantly.
-
-**Options:**
-
-*   `-c, --config <path>`
-    *   **Default:** `docmd.config.js` or `config.js`
-    *   **Description:** Specifies the path to the configuration file.
-
-*   `--port <number>`
-    *   **Default:** `3000`
-    *   **Description:** Specifies the port for the development server. If the port is in use, docmd will automatically try the next available one.
-    *   **Example:** `docmd dev --port 8080`
-
-*   `-p, --preserve`
-    *   **Default:** `false`
-    *   **Description:** Preserves existing asset files instead of updating them.
-
-*   `--silent`
-    *   **Default:** `false`
-    *   **Description:** Suppresses most log output in the console. Useful for running in automated environments.
-
-**Note:** The development server starts on port 3000 by default. If port 3000 is already in use, the server will automatically try the next available port (3001, 3002, etc.) until it finds an open port.
-
-## Global Options (Apply to all commands)
-
-*   `--version`
-    *   **Usage:** `docmd --version`
-    *   **Description:** Displays the installed version of `docmd`.
-*   `--help`
-    *   **Usage:** `docmd --help` or `docmd <command> --help` (e.g., `docmd build --help`)
-    *   **Description:** Displays help information for `docmd` or a specific command, including available options.
-
-This reference should help you effectively use `docmd` from your command line. For more detailed explanations of how these commands fit into the workflow, see the [Getting Started > Basic Usage](/getting-started/basic-usage/) guide.

package/docs/comparison.md

@@ -1,56 +0,0 @@
----
-title: "Comparison between docmd, Docusaurus, MkDocs, Mintlify and more"
-description: "A detailed comparison of docmd against Docusaurus, MkDocs, Mintlify, and Docsify."
----
-
-# Comparing Documentation Tools
-
-Choosing the right tool depends on your specific needs. `docmd` was built to fill the gap between "too simple" (basic parsers) and "too heavy" (full application frameworks).
-
-## Feature Matrix
-
-| Feature | docmd | Docusaurus | MkDocs (Material) | Mintlify | Docsify |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| **Core Tech** | Node.js (Native) | React.js | Python | Proprietary | JS (Runtime) |
-| **Output** | Static HTML | React SPA (Hydrated) | Static HTML | Hosted / Next.js | None (Runtime SPA) |
-| **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.
-*   **Choose docmd if:** You want a fast, lightweight site that is just HTML/CSS. You don't want to maintain a React dependency tree just to display documentation.
-
-### vs. MkDocs (Material)
-**MkDocs** is widely loved but requires a Python environment.
-*   **Choose MkDocs if:** You are already in the Python ecosystem or need its mature plugin ecosystem immediately.
-*   **Choose docmd if:** You are a JavaScript/Node.js developer. You want to run `npm install` and go, without dealing with `pip`, `requirements.txt`, or Python version conflicts.
-
-### vs. Mintlify
-**Mintlify** is a modern, hosted documentation platform focused on design.
-*   **Choose Mintlify if:** You have a budget and don't want to touch *any* code or configuration. You just want to upload markdown and pay someone to host and style it.
-*   **Choose docmd if:** You want full control over your HTML/CSS and want to host your docs for **free** on GitHub Pages, Vercel, or Netlify without branding watermarks or custom domain fees.
-
-### vs. Docsify
-**Docsify** is a "magical" generator that parses Markdown on the fly in the browser.
-*   **Choose Docsify if:** You absolutely cannot run a build step (e.g., you are hosting on a legacy server that only serves static files and you can't run CI/CD).
-*   **Choose docmd if:** You care about **SEO** and **Performance**. Docsify requires the user's browser to download the Markdown parser and the content before rendering anything, which is bad for search engines and users on slow connections. `docmd` builds real HTML files that load instantly.
-
-## The docmd Philosophy
-
-We believe documentation tools shouldn't be heavy. `docmd` generates **zero-clutter** websites. We don't ship a heavy JavaScript framework to the client just to render text. This results in:
-
-1.  **Better SEO:** Search engines love clean, semantic HTML.
-2.  **Faster Load Times:** No "hydration" delay or runtime parsing.
-3.  **Easier Maintenance:** Standard web technologies (CSS/JS), no framework knowledge required.

package/docs/configuration.md

@@ -1,289 +0,0 @@
----
-title: "Configuration"
-description: "Detailed explanation of all options available in the docmd config file, including logo, theming, plugins, and more."
----
-
-# Configuration (`docmd.config.js`)
-
-`docmd` uses a `docmd.config.js` file in the root of your project... For backward compatibility, it will fall back to using `config.js` if `docmd.config.js` is not found.
-
-## Example `docmd.config.js` Structure:
-
-```javascript
-module.exports = {
-  siteTitle: 'My Awesome Project Docs',
-  logo: {
-    light: '/assets/images/logo-light.svg', // Path to logo for light mode
-    dark: '/assets/images/logo-dark.svg',   // Path to logo for dark mode
-    alt: 'My Project Logo',                 // Alt text for the logo
-    // href: '/',                           // Optional: link for the logo, defaults to site root
-    // height: '30px',                      // Optional: specify height via CSS is often better
-  },
-  srcDir: 'docs',
-  outputDir: 'site',
-
-  search: true,
-
-  sidebar: {
-    collapsible: true,
-    defaultCollapsed: false,
-  },
-
-  theme: {
-    name: 'sky',
-    defaultMode: 'light',
-    enableModeToggle: true,
-    positionMode: 'top', // 'top' or 'bottom'
-    customCss: [            // Array of paths to your custom CSS files
-      // '/css/override-styles.css', // Paths are relative to the outputDir root
-    ],
-    // options: { /* Future: theme-specific options */ }
-  },
-
-  customJs: [               // Array of paths to your custom JS files
-    // '/js/extra-functionality.js', // Loaded at the end of the body
-  ],
-
-  autoTitleFromH1: true,
-  copyCode: true,
-
-  sponsor: {
-    enabled: true,
-    title: 'Sponsor the Project',
-    link: 'https://github.com/sponsors/mgks',
-  },
-
-  plugins: {
-    // SEO Plugin Configuration
-    seo: {
-      defaultDescription: 'A fantastic site about interesting things.',
-      openGraph: { 
-        defaultImage: '/assets/images/og-social-default.png'
-      },
-      twitter: { 
-        cardType: 'summary_large_image', 
-        siteUsername: '@MyProject' 
-      }
-    },
-
-    // Google Analytics 4
-    analytics: {
-      googleV4: { 
-        measurementId: 'G-XXXXXXXXXX' 
-      }
-    },
-    
-    // Sitemap generation
-    sitemap: {
-      defaultChangefreq: 'weekly',
-      defaultPriority: 0.8
-    }
-  },
-
-  navigation: [
-    { title: 'Home', path: '/', icon: 'home' }, // Icon names correspond to SVGs
-    {
-      title: 'Guides',
-      icon: 'book-open',
-      collapsible: true, // This makes the 'Guides' section collapsible
-      children: [
-        { title: 'Installation', path: '/guides/installation', icon: 'download' },
-        { title: 'Project GitHub', path: 'https://github.com/mgks/docmd', icon: 'github', external: true }
-      ],
-    },
-  ],
-  footer: '© ' + new Date().getFullYear() + ' My Project. Made with [docmd](https://github.com/mgks/docmd).',
-  favicon: '/assets/favicon.ico', // Path relative to outputDir root
-};
-```
-
-## Top-Level Options
-
-### `siteTitle`
-*   **Type:** `String`
-*   **Required:** Yes
-*   **Description:** The main title for your documentation site. Used as a fallback if no logo is provided, in the HTML `<title>` tag, and potentially by plugins (e.g., SEO).
-*   **Example:** `siteTitle: 'My Product Documentation'`
-
-### `logo`
-*   **Type:** `Object`
-*   **Optional**
-*   **Description:** Configures a logo to be displayed in the site header/sidebar, typically replacing or complementing the `siteTitle` text.
-*   **Properties:**
-    *   `light` (String, Required if using logo): Path to the logo image file for light mode. Path should be relative to the `outputDir` root (e.g., `/assets/images/logo-light.svg`).
-    *   `dark` (String, Required if using logo): Path to the logo image file for dark mode.
-    *   `alt` (String, Required if using logo): Alternative text for the logo image (for accessibility).
-    *   `href` (String, Optional): The URL the logo should link to. Defaults to the site root (`/`).
-    *   `height` (String, Optional): Suggested height for the logo (e.g., `'30px'`, `'2rem'`). It's often better to control size via CSS for more flexibility.
-*   **Note:** Ensure your logo image files are copied to the specified paths within your `outputDir` during the build. Usually, this means placing them in an assets folder that `docmd` copies.
-
-### `srcDir`
-*   **Type:** `String`
-*   **Default:** `'docs'`
-*   **Description:** Directory containing your Markdown source files.
-
-### `outputDir`
-*   **Type:** `String`
-*   **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.
-
-### `autoTitleFromH1`
-*   **Type:** `Boolean`
-*   **Default:** `true`
-*   **Description:** If `true`, `docmd` will automatically use the content of the first H1 tag (`# Title`) as the page title if no `title` is specified in the frontmatter. If set to `false` and a page has no `title` in its frontmatter, the page header will be hidden.
-*   **Example:** 
-    ```javascript
-    // With autoTitleFromH1: true (default)
-    // Markdown file with: # My Page Title
-    // Will automatically set the page title to "My Page Title"
-    
-    // With autoTitleFromH1: false
-    // You must explicitly set title in frontmatter:
-    // ---
-    // title: "My Page Title"
-    // ---
-    ```
-
-### `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.
-
-### `sidebar.collapsible`
-*   **Type:** `Boolean`
-*   **Default:** `false`
-*   **Description:** If `true`, a toggle button is added to the header, allowing users to show or hide the sidebar. The user's preference is saved in `localStorage`.
-
-### `sidebar.defaultCollapsed`
-*   **Type:** `Boolean`
-*   **Default:** `false`
-*   **Description:** If `sidebar.collapsible` is `true`, this option sets the default state of the sidebar to collapsed. A user's saved preference will override this.
-
-## `theme` (Object)
-
-Configures the visual theme of your site.
-
-### `theme.name`
-*   **Type:** `String`
-*   **Default:** `'default'`
-*   **Description:** Specifies which built-in `docmd` theme to use. Future versions may offer multiple themes like `'classic'`, `'minimalist-pro'`. Each theme would correspond to a CSS file (e.g., `theme-default.css`).
-*   **See Also:** [Available Themes](/theming/available-themes/)
-
-### `theme.defaultMode`
-*   **Type:** `String`
-*   **Default:** `'light'`
-*   **Values:** `'light'` or `'dark'`
-*   **Description:** Sets the default color mode (light or dark) for the site.
-
-### `theme.enableModeToggle`
-*   **Type:** `Boolean`
-*   **Default:** `true` (assuming it's now a core feature)
-*   **Description:** If `true`, a UI toggle button will be displayed allowing users to switch between light and dark modes. Their preference is typically saved in `localStorage`.
-
-### `theme.positionMode`
-*   **Type:** `String`
-*   **Default:** `'bottom'`
-*   **Values:** `'top'` or `'bottom'`
-*   **Description:** Sets the position of the light/dark mode toggle button. `'top'` places it in the page header (top right), while `'bottom'` places it at the bottom of the sidebar.
-*   **Example:** `positionMode: 'top'` - Useful for sites where you want the theme toggle to be more prominent and easily accessible.
-
-### `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 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']`
-
-### `theme.options` (Future Placeholder)
-*   **Type:** `Object`
-*   **Description:** A placeholder for theme-specific configuration options if a theme (`theme.name`) exposes its own settings (e.g., primary color, font choices for a more advanced theme).
-
-## `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 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']`
-
-## `plugins` (Object)
-*   **Type:** `Object`
-*   **Default:** `{}`
-*   **Description:** An object to configure and enable plugins. `docmd` ships with core plugins like SEO, Analytics, and Sitemap that you can configure here.
-*   **Format:** Each key in the object represents a plugin name, and its value is an object containing the plugin's configuration options.
-*   **Built-in Plugin Examples:**
-    *   `seo: { defaultDescription: '...', openGraph: { ... }, ... }`
-    *   `analytics: { googleV4: { measurementId: 'G-XXXXXXXXXX' } }`
-    *   `sitemap: { defaultChangefreq: 'weekly', defaultPriority: 0.8 }`
-*   **See Also:** [Plugins](/plugins/)
-
-## `editLink` (Object, Optional)
-*   **Type:** `Object`
-*   **Description:** Configures a link in the page footer that points to the source file on GitHub (or GitLab/Bitbucket), allowing users to propose changes.
-*   **Properties:**
-    *   `enabled` (Boolean): Set to `true` to show the link.
-    *   `baseUrl` (String): The base URL to your repository's documentation source folder.
-        *   *GitHub Example:* `https://github.com/USERNAME/REPO/edit/main/docs`
-        *   *Note:* Do not include a trailing slash. `docmd` appends the file path automatically.
-    *   `text` (String, Optional): The text to display. Defaults to "Edit this page".
-*   **Example:**
-    ```javascript
-    editLink: {
-      enabled: true,
-      baseUrl: 'https://github.com/mgks/docmd/edit/main/docs',
-      text: 'Edit on GitHub'
-    }
-    ```
-
-## `navigation` (Array of Objects)
-*   **Description:** Defines the sidebar navigation. (Content mostly same as before, but add the `icon` property explanation).
-*   **Navigation Item Properties:**
-    *   `title` (String, Required)
-    *   `path` (String, Required for direct links)
-    *   `children` (Array, Optional)
-    *   `icon` (String, Optional): The name of an SVG icon to display next to the navigation item. `docmd` will look for an SVG file named `icon-name.svg` in its bundled assets (e.g., `home` for `home.svg`). Ensure the chosen icon name corresponds to an available SVG. See [Theming > Icons](/theming/icons/) for more details.
-    *   `collapsible` (Boolean, Optional): If set to `true` on a parent item (an item with `children`), the item will become a collapsible accordion. It will be collapsed by default unless one of its children is the currently active page. User interactions (opening/closing) are saved in `sessionStorage`. Defaults to `false`.
-    *   `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`.
-    *   `collapsible` (Boolean, Optional): If set to `true` on a parent item (an item with `children`), the item will become a collapsible accordion. It will be collapsed by default unless one of its children is the currently active page. User interactions (opening/closing) are saved in `sessionStorage`. Defaults to `false`.
-
-## `footer` (String, Optional)
-*   **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 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'`.
-    *   `link` (String, Required if enabled): URL for the sponsor link. Should open in a new tab.
-*   **Example:**
-    ```javascript
-    sponsor: {
-      enabled: true,
-      title: 'Sponsor the Project',
-      link: 'https://github.com/sponsors/mgks'
-    }
-    ```
-*   **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. **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/containers/buttons.md

@@ -1,88 +0,0 @@
----
-title: "Container: Buttons"
-description: "How to create stylish, clickable buttons within your documentation for calls to action."
----
-
-# Buttons
-
-The `button` container allows you to easily create a stylish, clickable button. It's perfect for calls to action, such as linking to a download page, an external resource, or another section of your documentation.
-
-## Usage
-
-The button container is a self-contained component. You provide its text, URL, and an optional color as arguments.
-
-::: callout info Important Notes
-- Container blocks (like `::: button`) should be preceded by a blank line to ensure proper parsing by the markdown processor.
-:::
-
-**Syntax:**
-```bash
-::: button Button_Text /path/to/link color:#hexcode
-::: button Button_Text external:/external-url color:#hexcode
-```
-
--   **`Button_Text`**: The text to display on the button. Use underscores (`_`) for spaces.
--   **`/path/to/link`**: The URL the button should link to. For internal links, use relative paths.
--   **`external:/external-url`**: For external links that should open in a new tab, prefix the URL with `external:`.
--   **`[color:#hexcode]`**: (Optional) A custom background color for the button. If omitted, it will use the theme's default link color.
-
----
-
-## Examples
-
-### Standard Internal Button
-
-This button will use the default theme color and link to a section on the current page.
-
-**Code:**
-```bash
-::: button View_Examples #examples
-```
-
-**Rendered Preview:**
-::: button View_Examples #examples
-
-### External Link Button
-
-External links open in a new tab for better user experience.
-
-**Code:**
-```bash
-::: button GitHub_Repository external:https://github.com/mgks/docmd
-```
-
-**Rendered Preview:**
-::: button GitHub_Repository external:https://github.com/mgks/docmd
-
-### Button with Custom Color
-
-You can easily override the color for emphasis.
-
-**Code:**
-```bash
-::: button Getting_Started #getting-started color:#28a745
-```
-
-**Rendered Preview:**
-::: button Getting_Started #getting-started color:#28a745
-
-### Buttons Inside Other Containers
-
-Buttons are flexible and can be placed inside other containers, like cards or callouts, to create powerful components. This nesting is now reliable.
-
-**Code:**
-
-```bash
-::: card Feature Announcement
-Our latest feature is now available! Read the full documentation to learn more about how it works.
-::: button Read_More /path/to/feature/docs/
-:::
-```
-
-**Rendered Preview:**
-
-::: card Feature Announcement
-Our latest feature is now available! Read the full documentation to learn more about how it works.
-
-::: button Learn_More #customization
-:::