@mgks/docmd 0.1.0

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: mgks # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

package/.github/workflows/deploy-docmd.yml

@@ -0,0 +1,45 @@
+name: deploy docmd
+
+on:
+  push:
+    branches: [main] # Your default branch
+  workflow_dispatch: # Allows manual triggering
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js ⚙️
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22' # Use Node.js 22
+          cache: 'npm'
+
+      - name: Install Dependencies 📦
+        run: npm ci # Use ci for cleaner installs in CI
+
+      - name: Build docmd's Own Docs 🛠️
+        run: node ./bin/docmd.js build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+      - name: Deploy to GitHub Pages 🚀
+        id: deployment
+        uses: actions/deploy-pages@v4

package/.github/workflows/publish.yml

@@ -0,0 +1,84 @@
+name: Publish Package to NPM and GitHub Packages
+
+on:
+  release:
+    types: [created] # Triggers when a new GitHub Release is published
+  workflow_dispatch: # Allows manual triggering for testing
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write # Required for GitHub Packages
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        # Your package.json in the workspace should now have name: "@mgks/docmd"
+
+      - name: Set up Node.js (common for all steps)
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm' # Cache npm dependencies
+
+      - name: Install dependencies
+        run: npm ci
+
+      # Optional: Run build script if you have one for the package itself
+      # - name: Build package
+      #   run: npm run build
+
+      # Optional: Run tests
+      # - name: Test package
+      #   run: npm test
+
+      # --- Publish to NPM Registry (npmjs.com) ---
+      - name: Set up Node.js for npmjs.com
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22' # Redundant if already set, but harmless
+          registry-url: 'https://registry.npmjs.org/'
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} # Configures .npmrc for npmjs.com
+
+      # No need to change package.json name if it's already @mgks/docmd
+      # Just ensure no GPR-specific publishConfig is present
+      - name: Prepare package.json for npmjs.com
+        run: |
+          echo "package.json for npmjs.com publishing (should be @mgks/docmd):"
+          cat package.json
+          # Remove publishConfig if it exists, just in case
+          if jq -e '.publishConfig' package.json > /dev/null; then
+            echo "Removing publishConfig for npmjs.com publish"
+            jq 'del(.publishConfig)' package.json > package_temp.json && mv package_temp.json package.json
+          else
+            echo "No publishConfig found, package.json is ready for npmjs.com."
+          fi
+          cat package.json
+
+      - name: Publish to NPM Registry (npmjs.com)
+        # For scoped packages on npmjs.com, --access=public is needed for the first publish
+        # and if it's intended to be a public package.
+        run: npm publish --access=public
+
+      # --- Publish to GitHub Packages ---
+      - name: Set up Node.js for GitHub Packages
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22' # Redundant if already set, but harmless
+          registry-url: 'https://npm.pkg.github.com'
+          # scope: '@mgks' # Not strictly needed here if package.json name is already @mgks/docmd
+                           # but good for ensuring .npmrc is correctly configured for the @mgks scope.
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Configures .npmrc for GPR
+
+      # The package name is already @mgks/docmd from checkout (and npmjs.com step didn't change it).
+      # No jq transformation of the name is needed.
+      - name: Verify package.json for GitHub Packages
+        run: |
+          echo "package.json for GPR publishing (should be @mgks/docmd):"
+          cat package.json
+
+      - name: Publish to GitHub Packages
+        run: npm publish

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 mgks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+<p align="center">
+  <img src="https://github.com/mgks/docmd/blob/main/src/assets/images/docmd-logo.png" alt="docmd logo" width="65" />
+  <br />
+  <img src="https://github.com/mgks/docmd/blob/main/src/assets/images/logo-light.png" alt="docmd dark logo" width="200" />
+</p>
+
+<p align="center">
+  <b>Generate beautiful, lightweight static documentation sites from Markdown files.</b><br>
+  Zero clutter, just content.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@mgks/docmd"><img src="https://img.shields.io/npm/v/@mgks/docmd.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@mgks/docmd"><img src="https://img.shields.io/npm/dm/@mgks/docmd.svg" alt="npm downloads"></a>
+  <a href="https://github.com/mgks/docmd/blob/main/LICENSE"><img src="https://img.shields.io/github/license/mgks/docmd.svg" alt="license"></a>
+</p>
+
+Docmd (`docmd`) is a Node.js command-line tool dedicated to generating beautiful, lightweight static documentation sites from standard Markdown files. It champions the philosophy of "zero clutter, just content," prioritizing ease of use for documentation authors and a clean, performant experience for readers.
+
+## Features
+
+- 📝 **Markdown First** - Standard Markdown with YAML frontmatter
+- 🎨 **Beautiful Themes** - Multiple themes and light/dark modes with syntax highlighting
+- 🚀 **Fast & Lightweight** - Static site generation with minimal JS
+- 🧩 **Custom Components** - Callouts, cards, steps, and more
+- 🔌 **Built-in Plugins** - SEO, Analytics, and Sitemap support
+- 💻 **Simple CLI** - Easy `init`, `dev`, and `build` commands
+- 🌐 **Deploy Anywhere** - Deploy the generated sites anywhere (GitHub Pages, Netlify, Vercel, etc.).
+
+## Installation
+
+### From npm
+
+```bash
+# Global installation (recommended)
+npm install -g @mgks/docmd
+
+# Local project installation
+npm install --save-dev @mgks/docmd
+```
+
+### Quick Start
+
+```bash
+# Initialize a new documentation project
+docmd init
+
+# Start the development server
+docmd dev
+
+# Build for production
+docmd build
+```
+
+### Documentation
+
+For complete documentation, visit **[docmd.mgks.dev](https://docmd.mgks.dev)**
+
+## Contributing
+
+Contributions are welcome! Please check our [contributing guidelines](https://docmd.mgks.dev/contributing/) to get started.
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/docmd.git`
+3. Install dependencies: `npm install`
+4. Make your changes and test them
+5. Submit a pull request
+
+## License
+
+`docmd` is licensed under the [MIT License](LICENSE).
+
+## Support the Project
+
+If you find `docmd` useful, please consider:
+
+- Starring the repository on GitHub
+- Sharing it with others who might benefit
+- Reporting issues or submitting pull requests
+
+**[GitHub Sponsors](https://github.com/sponsors/mgks): Become a monthly or one-time GitHub sponsor to support docmd & other projects developed by [me](https://mgks.dev).**
+
+<br /><img src="https://forthebadge.com/images/badges/built-with-love.svg" alt="Built with Love">

package/bin/docmd.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const { version } = require('../package.json');
+const { initProject } = require('../src/commands/init');
+const { buildSite } = require('../src/commands/build');
+const { startDevServer } = require('../src/commands/dev');
+
+const program = new Command();
+
+program
+  .name('docmd')
+  .description('Generate beautiful, lightweight static documentation sites directly from your Markdown files.')
+  .version(version);
+
+program
+  .command('init')
+  .description('Initialize a new docmd project (creates docs/ and config.js)')
+  .action(async () => {
+    try {
+      await initProject();
+      console.log('✅ docmd project initialized successfully!');
+    } catch (error) {
+      console.error('❌ Error initializing project:', error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('build')
+  .description('Build the static site from Markdown files and config.js')
+  .option('-c, --config <path>', 'Path to config.js file', 'config.js')
+  .action(async (options) => {
+    try {
+      console.log('🚀 Starting build process...');
+      await buildSite(options.config);
+      console.log('✅ Build complete! Site generated in `site/` directory.');
+    } catch (error) {
+      console.error('❌ Build failed:', error.message);
+      console.error(error.stack);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('dev')
+  .description('Start a live preview development server')
+  .option('-c, --config <path>', 'Path to config.js file', 'config.js')
+  .action(async (options) => {
+    try {
+      await startDevServer(options.config);
+    } catch (error) {
+      console.error('❌ Dev server failed:', error.message);
+      console.error(error.stack);
+      process.exit(1);
+    }
+  });
+
+program.parse(process.argv);
+
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}

package/config.js

@@ -0,0 +1,137 @@
+// config.js (for docmd's own documentation)
+module.exports = {
+  // Core Site 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
+
+  // Logo Configuration
+  logo: {
+    light: '/assets/images/logo-light.png', // Path relative to outputDir root
+    dark: '/assets/images/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
+    // height: '30px',                      // Optional: control via CSS is often better
+  },
+
+  // Directory Configuration
+  srcDir: 'docs',       // Source directory for Markdown files
+  outputDir: 'site',    // Directory for generated static site
+
+  // Theme Configuration
+  theme: {
+    name: 'sky',            // Themes: 'default', 'sky'
+    defaultMode: 'light',   // Initial color mode: 'light' or 'dark'
+    enableModeToggle: true, // Show UI button to toggle light/dark modes
+    customCss: [            // Array of paths to custom CSS files
+      '/assets/css/toc.css', // Custom TOC styles
+    ],
+    // options: { /* Future: theme-specific options */ }
+  },
+
+  // Custom JavaScript Files
+  customJs: [               // Array of paths to custom JS files, loaded at end of body
+    // '/assets/js/custom-script.js', // Paths relative to outputDir root
+  ],
+
+  // Plugins Configuration (Object format)
+  // Plugins are configured here. docmd will look for these keys.
+  plugins: {
+    // SEO Plugin Configuration
+    // Most SEO data is pulled from page frontmatter (title, description, image, etc.)
+    // These are fallbacks or site-wide settings.
+    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
+        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)
+      }
+    },
+    // 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
+      // }
+    },
+    // Enable Sitemap plugin
+    sitemap: {
+      defaultChangefreq: 'weekly',
+      defaultPriority: 0.8
+    }
+    // Add other future plugin configurations here by their key
+  },
+
+  // Navigation Structure (Sidebar)
+  // Icons are kebab-case names from Lucide Icons (https://lucide.dev/)
+  navigation: [
+      { title: 'GitHub', path: 'https://github.com/mgks/docmd', icon: 'github', external: true },
+      { title: 'Home', path: '/', icon: 'home' }, // Corresponds to docs/index.md
+      {
+        title: 'Getting Started',
+        icon: 'rocket', // Lucide: rocket
+        path: '/getting-started/', // Path to the index.md in this folder
+        children: [
+          { title: 'Installation', path: '/getting-started/installation', icon: 'download' }, // Lucide: download
+          { title: 'Basic Usage', path: '/getting-started/basic-usage', icon: 'play' },      // Lucide: play
+        ],
+      },
+      {
+        title: 'Writing Content',
+        icon: 'pencil', // Lucide: pencil
+        path: '/writing-content/',
+        children: [
+          { title: 'Frontmatter', path: '/writing-content/frontmatter', icon: 'file-text' },      // Lucide: file-text
+          { title: 'Markdown Syntax', path: '/writing-content/markdown-syntax', icon: 'code-2' }, // Lucide: code-2
+          { title: 'Custom Containers', path: '/writing-content/custom-containers', icon: 'box' }, // Lucide: box
+        ],
+      },
+      { title: 'Configuration', path: '/configuration', icon: 'settings' }, // Lucide: settings or cog
+      {
+        title: 'Theming',
+        icon: 'palette', // Lucide: palette
+        path: '/theming/',
+        children: [
+          { title: 'Available Themes', path: '/theming/available-themes', icon: 'layout-grid' }, // Lucide: layout-grid
+          { title: 'Light & Dark Mode', path: '/theming/light-dark-mode', icon: 'sun-moon' },     // Lucide: sun-moon
+          { title: 'Custom CSS & JS', path: '/theming/custom-css-js', icon: 'file-code' },     // Lucide: file-code
+          { title: 'Icons', path: '/theming/icons', icon: 'image' },                        // Lucide: image
+        ],
+      },
+      {
+        title: 'Plugins',
+        icon: 'puzzle', // Lucide: puzzle
+        path: '/plugins/',
+        children: [
+          { title: 'SEO & Meta Tags', path: '/plugins/seo', icon: 'search' },      // Lucide: search
+          { title: 'Analytics', path: '/plugins/analytics', icon: 'bar-chart' },   // Lucide: bar-chart
+          { title: 'Sitemap', path: '/plugins/sitemap', icon: 'map' },             // Lucide: map
+        ],
+      },
+      { title: 'CLI Commands', path: '/cli-commands', icon: 'terminal' }, // Lucide: terminal
+      { title: 'Deployment', path: '/deployment', icon: 'upload-cloud' }, // Lucide: upload-cloud
+      { title: 'Contributing', path: '/contributing', icon: 'users-2' },   // Lucide: users-2
+      // Example of an external link:
+  ],
+
+  // Footer Configuration
+  // Markdown is supported here.
+  footer: '© ' + new Date().getFullYear() + ' Project docmd.',
+
+  // Favicon Configuration
+  // Path relative to outputDir root
+  favicon: '/assets/favicon.ico',
+};

package/docs/cli-commands.md

@@ -0,0 +1,87 @@
+---
+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.
+*   `config.js`: The main configuration file for your site, pre-filled with default settings.
+
+If a `docs/` directory or `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 `config.js`, defaults to `docs/`), processes them along with your `config.js`, and generates a complete static website in the output directory (specified by `outputDir` in `config.js`, defaults to `site/`).
+
+The output `site/` directory contains all the HTML, CSS, JavaScript, and other assets needed to deploy your documentation.
+
+**Options:**
+
+*   `-c, --config <path>`
+    *   **Default:** `config.js`
+    *   **Description:** Specifies the path to the configuration file. Useful if your config file is not named `config.js` or is not in the project root.
+    *   **Example:** `docmd build --config my.docmd.config.js`
+
+## `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, `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:** `config.js`
+    *   **Description:** Specifies the path to the configuration file.
+    *   **Example:** `docmd dev --config my.docmd.config.js`
+*   `-p, --port <port_number>` (Future Option)
+    *   **Description:** While not yet implemented, a future version might allow specifying a custom port for the development server. Currently, it defaults to port 3000 or the next available port if 3000 is in use.
+
+## 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.