@mgks/docmd 0.2.5 → 0.2.7

package/.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,48 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at hello@mgks.dev.
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,58 @@
+name: 🐞 Bug Report
+description: Create a report to help us improve docmd
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: input
+    id: version
+    attributes:
+      label: docmd version
+      description: What version of docmd are you using? (e.g. 0.2.6)
+      placeholder: 0.2.6
+    validations:
+      required: true
+  - type: input
+    id: node-version
+    attributes:
+      label: Node.js version
+      placeholder: v20.x
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: OS
+      options:
+        - macOS
+        - Windows
+        - Linux
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of what the bug is.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Please provide the steps to reproduce the behavior.
+      placeholder: |
+        1. Run 'docmd init'
+        2. Add configuration...
+        3. Run 'docmd build'
+        4. See error...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: A clear and concise description of what you expected to happen.

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,27 @@
+name: 💡 Feature Request
+description: Suggest an idea for this project
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a new feature!
+  - type: textarea
+    id: problem
+    attributes:
+      label: Is your feature request related to a problem?
+      description: A clear and concise description of what the problem is.
+      placeholder: I'm always frustrated when...
+  - type: textarea
+    id: solution
+    attributes:
+      label: Describe the solution you'd like
+      description: A clear and concise description of what you want to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Describe alternatives you've considered
+      description: A clear and concise description of any alternative solutions or features you've considered.

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+## Description
+<!-- Please include a summary of the change and which issue is fixed. -->
+
+Fixes # (issue)
+
+## Type of change
+- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
+- [ ] ✨ New feature (non-breaking change which adds functionality)
+- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] 📝 Documentation update
+
+## Checklist:
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings

package/.github/SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.2.x   | :white_check_mark: |
+| 0.1.x   | :x:                |
+
+## Reporting a Vulnerability
+
+Use this section to tell people how to report a vulnerability.
+
+Please do not report security vulnerabilities through public GitHub issues.
+
+If you have discovered a security vulnerability in `docmd`, please email hello@mgks.dev.
+
+We will do our best to respond within 48 hours.

package/.github/workflows/publish.yml

@@ -2,83 +2,46 @@ name: Publish Package to NPM and GitHub Packages
 
 on:
   release:
-    types: [created] # [created, published] Triggers when a new GitHub Release is created or published
-  workflow_dispatch: # Allows manual triggering for testing
+    types: [published]
+  workflow_dispatch:
 
 jobs:
   publish:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      packages: write # Required for GitHub Packages
+      packages: write
     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)
+      - name: Set up Node.js v22
         uses: actions/setup-node@v4
         with:
           node-version: '22'
-          cache: 'npm' # Cache npm dependencies
+          cache: 'npm'
 
       - 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
+      # ------------------------------------------
+      - name: Configure NPM for public registry
+        run: echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > ~/.npmrc
 
-      # 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.
+      - name: Publish to NPM Registry
         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
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
-      # 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
+      # ----------------------------------------
+      # --- Publish to GitHub Packages (GPR) ---
+      # ----------------------------------------
+      - name: Configure NPM for GitHub Packages registry
+        run: echo "//npm.pkg.github.com/:_authToken=${{ secrets.GITHUB_TOKEN }}" > ~/.npmrc
 
       - name: Publish to GitHub Packages
-        run: npm publish
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/README.md

@@ -5,8 +5,8 @@
 </p>
 
 <p align="center">
-  <b>Generate beautiful, lightweight static documentation sites from Markdown files.</b><br>
-  Zero clutter, just content.
+  <b>Generate beautiful, lightweight static documentation sites from Markdown files.</b>
+  <br>Zero clutter, just content.
 </p>
 
 <p align="center">
@@ -15,71 +15,109 @@
   <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.
+Docmd is a Node.js command-line tool for generating fast, beautiful, and lightweight static documentation sites from standard Markdown files. It champions the philosophy of "zero clutter, just content," prioritizing a simple authoring experience and a clean, performant result for readers.
 
-#### 🟢 [Live Preview](https://docmd.mgks.dev): Documentation site powered entirely by *Docmd*, serving as both the official docs and a live demo.
+**:rocket: [Live Preview](https://docmd.mgks.dev): Official documentation site powered by `docmd`.**
 
-## Features
+## Key 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
-- 🎭 **No-Style Pages** - Create custom standalone pages with complete HTML control
-- 🖌️ **Custom Styling** - Add custom CSS/JS and HTML directly in frontmatter
-- 💻 **Simple CLI** - Easy `init`, `dev`, and `build` commands
-- 🌐 **Deploy Anywhere** - Deploy the generated sites anywhere (GitHub Pages, Netlify, Vercel, etc.)
+-   **Markdown First:** Write your content in standard Markdown with simple YAML frontmatter.
+-   **Beautiful Themes:** Comes with multiple built-in themes (`sky`, `ruby`, `retro`) and automatic light/dark mode support.
+-   **Fast & Lightweight:** Blazing fast static site generation with a minimal client-side footprint.
+-   **Rich Content:** Go beyond basic Markdown with custom components like callouts, cards, steps, tabs, and Mermaid diagrams.
+-   **Built-in Plugins:** SEO meta tags, sitemap, and analytics are all included out-of-the-box.
+-   **No-Style Pages:** Create completely custom pages (like landing pages) with full control over the HTML.
+-   **Customizable:** Easily extend or override styles with your own CSS and JavaScript.
+-   **Smart CLI:** Intelligent configuration validation catches typos and errors early. Simple workflow with `init`, `dev`, and `build`.
+-   **Deploy Anywhere:** The generated `site/` folder can be hosted on any static web host (GitHub Pages, Netlify, Vercel, etc.).
 
-## Installation
+## Installation and Usage
 
-### From npm
+**Prerequisites:** [Node.js](https://nodejs.org/) (version 22.x or higher) is required.
 
+### Global Installation (Recommended)
+
+This is the recommended approach for developers who will use `docmd` across multiple projects. It makes the `docmd` command available system-wide.
+
+**1. Install Globally:**
 ```bash
-# Global installation (recommended)
 npm install -g @mgks/docmd
-
-# Local project installation
-npm install --save-dev @mgks/docmd
 ```
 
-### Quick Start
+**2. Basic Workflow:**
+Once installed, you can use the `docmd` command directly in any project folder.
 
-```bash
-# Initialize a new documentation project
-docmd init
+*   **Initialize a Project:**
+    ```bash
+    # This creates docs/, docmd.config.js, and a sample index.md
+    docmd init
+    ```
 
-# Start the development server
-docmd dev
+*   **Start the Dev Server:**
+    ```bash
+    # Starts a live-reloading server at http://localhost:3000
+    docmd dev
+    ```
 
-# Build for production
-docmd build
-```
+*   **Build for Production:**
+    ```bash
+    # Generates the static site into the `site/` directory
+    docmd build
+    ```
 
-### Documentation
+### Quick Start (Alternative)
 
-For complete documentation, visit **[docmd.mgks.dev](https://docmd.mgks.dev)**
+If you prefer not to install packages globally, you can use `npx` to run `docmd` on-demand. This is a great way to try it out or use it in a single project.
 
-## Contributing
+1.  **Create and Initialize Your Project:**
+    This command will download the latest version, create a `my-docs` folder, and set up the project files inside it.
+    ```bash
+    npx @mgks/docmd init my-docs
+    ```
 
-Contributions are welcome! Please check our [contributing guidelines](https://docmd.mgks.dev/contributing/) to get started.
+2.  **Start the Development Server:**
+    Navigate into your new project and use `npx` again to start the server.
+    ```bash
+    cd my-docs
+    npx @mgks/docmd dev
+    ```
 
-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
+Your new documentation site is now running at `http://localhost:3000`.
 
-## License
+## Documentation
+
+For a complete guide, visit the official documentation: **[docmd.mgks.dev](https://docmd.mgks.dev)**.
 
-`docmd` is licensed under the [MIT License](https://github.com/mgks/docmd/blob/main/LICENSE).
+### Essential Topics
+-   **[Getting Started](https://docmd.mgks.dev/getting-started/installation/):** Installation and basic CLI usage.
+-   **[Custom Containers](https://docmd.mgks.dev/content/containers/):** How to use Callouts, Cards, Tabs, and Steps.
+-   **[Theming](https://docmd.mgks.dev/theming/):** Customizing colors, dark mode, and adding your logo.
+-   **[Plugins](https://docmd.mgks.dev/plugins/):** SEO, Analytics, and Sitemap configuration.
+-   **[Recipes](https://docmd.mgks.dev/recipes/):** Step-by-step guides for common tasks like Custom Fonts and Landing Pages.
+-   **[Comparison](https://docmd.mgks.dev/comparison/):** How `docmd` stacks up against Docusaurus, MkDocs, and others.
+
+## Contributing
+
+We welcome contributions of all kinds! Whether it's reporting a bug, suggesting a feature, or submitting a pull request, your help is appreciated.
+
+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 thoroughly.
+5.  Submit a pull request to the `main` branch.
+
+Please check our [contributing guidelines](https://docmd.mgks.dev/contributing/) for more detailed information.
 
 ## 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
+-   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 sponsor to support the ongoing development of `docmd`.**
+
+## License
 
-**[GitHub Sponsors](https://github.com/sponsors/mgks): Become a monthly or one-time GitHub sponsor to support docmd & other projects developed by [@mgks](https://mgks.dev).**
+Docmd is licensed under the [MIT License](https://github.com/mgks/docmd/blob/main/LICENSE).

package/bin/docmd.js

@@ -7,6 +7,7 @@ const { version } = require('../package.json');
 const { initProject } = require('../src/commands/init');
 const { buildSite } = require('../src/commands/build');
 const { startDevServer } = require('../src/commands/dev');
+const { printBanner } = require('../src/core/logger');
 
 // Helper function to find the config file
 const findConfigFile = () => {
@@ -52,6 +53,8 @@ program
   .option('--silent', 'Suppress log output')
   .action(async (options) => {
     try {
+      if (!options.silent) { printBanner(); }
+
       const originalLog = console.log;
       if (options.silent) { console.log = () => {}; }
 
@@ -68,7 +71,7 @@ program
 
     } catch (error) {
       console.error('❌ Build failed:', error.message);
-      console.error(error.stack);
+      // console.error(error.stack);
       process.exit(1);
     }
   });
@@ -83,6 +86,8 @@ program
   .option('--silent', 'Suppress log output')
   .action(async (options) => {
     try {
+      if (!options.silent) { printBanner(); }
+
       if (options.silent) {
         const originalLog = console.log;
         console.log = (message) => {
@@ -96,7 +101,7 @@ program
 
     } catch (error) {
       console.error('❌ Dev server failed:', error.message);
-      console.error(error.stack);
+      // console.error(error.stack);
       process.exit(1);
     }
   });

package/bin/postinstall.js

@@ -0,0 +1,14 @@
+// bin/postinstall.js
+
+const chalk = require('chalk');
+
+// This script runs after 'npm install', runs only when the user installs it globally and not in a CI environment
+
+if (process.env.npm_config_global && !process.env.CI) {
+  console.log(chalk.green('\n🎉 Thank you for installing docmd!'));
+  console.log('\nTo get started, run the following commands:');
+  console.log(`\n  ${chalk.cyan('docmd init my-awesome-docs')}`);
+  console.log(`  ${chalk.cyan('cd my-awesome-docs')}`);
+  console.log(`  ${chalk.cyan('npm start')}`);
+  console.log('\nFor complete documentation, visit: https://docmd.mgks.dev');
+}

package/config.js

@@ -155,9 +155,21 @@ module.exports = {
           { 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 },
@@ -169,7 +181,7 @@ module.exports = {
   // Sponsor Ribbon Configuration
   sponsor: {
     enabled: true,                    // Enable/disable the sponsor ribbon
-    title: 'Support docmd',     // Text to display on the ribbon
+    title: 'Sponsor',     // Text to display on the ribbon
     link: 'https://github.com/sponsors/mgks', // URL for the sponsor link
   },
 

package/docs/comparison.md

@@ -0,0 +1,51 @@
+---
+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 |
+| **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
+
+### 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/overview.md

@@ -3,7 +3,13 @@ title: "Minimalist Markdown Docs Generator"
 description: "Generate beautiful, lightweight static documentation sites directly from your Markdown files with docmd. Zero clutter, just content."
 ---
 
-# docmd
+```
+   _                 _ 
+ _| |___ ___ _____ _| |
+| . | . |  _|     | . |
+|___|___|___|_|_|_|___|
+
+```
 
 **Generate beautiful, lightweight static documentation sites directly from your Markdown files. Zero clutter, just content.**
 

package/docs/recipes/custom-fonts.md

@@ -0,0 +1,43 @@
+---
+title: "Recipe: Custom Fonts"
+description: "How to add Google Fonts or custom typefaces to your documentation."
+---
+
+# Adding Custom Fonts
+
+You can easily change the typography of your `docmd` site using CSS variables and a custom stylesheet.
+
+## 1. Select a Font
+Go to [Google Fonts](https://fonts.google.com) and select the font you want (e.g., "Poppins"). Copy the `@import` URL.
+
+## 2. Create a Custom CSS File
+Create a file in your project at `assets/css/typography.css`.
+
+```css
+/* assets/css/typography.css */
+@import url('https://fonts.googleapis.com/css2?family=Poppins:wght@400;600;700&display=swap');
+
+:root {
+  /* Override the default sans-serif font variable */
+  --font-family-sans: 'Poppins', system-ui, -apple-system, sans-serif;
+}
+```
+
+## 3. Register in Config
+Add the file to your `docmd.config.js`:
+
+```javascript
+module.exports = {
+  // ...
+  theme: {
+    name: 'default',
+    customCss: [
+      '/assets/css/typography.css' // Points to your new file
+    ]
+  }
+  // ...
+}
+```
+
+## 4. Restart
+Run `docmd dev`. Your site will now use Poppins!