@mgks/docmd 0.3.2 → 0.3.4

package/docs/content/no-style-example.md

@@ -1,112 +0,0 @@
----
-title: "No-Style Page Example"
-description: "An example of a page using the no-style feature"
-noStyle: true
-components:
-  meta: true
-  favicon: true
-  css: true
-  theme: true
-  scripts: true
-  mainScripts: true
-copyCode: true
-customHead: |
-  <style>
-    body {
-      font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
-      margin: 0;
-      padding: 0;
-      line-height: 1.6;
-    }
-    .container {
-      max-width: 800px;
-      margin: 0 auto;
-      padding: 40px 20px;
-    }
-    .header {
-      text-align: center;
-      margin-bottom: 40px;
-    }
-    .header h1 {
-      font-size: 3rem;
-      margin-bottom: 10px;
-      color: #4a6cf7;
-    }
-    .header p {
-      font-size: 1.2rem;
-      color: #666;
-    }
-    .content {
-      background-color: #f8f9fa;
-      padding: 30px;
-      border-radius: 8px;
-      box-shadow: 0 2px 10px rgba(0,0,0,0.05);
-    }
-    .button {
-      display: inline-block;
-      padding: 12px 24px;
-      background-color: #4a6cf7;
-      color: white;
-      text-decoration: none;
-      border-radius: 4px;
-      font-weight: 600;
-      margin-top: 20px;
-    }
-    .button:hover {
-      background-color: #3a5ce4;
-    }
-    [data-theme="dark"] {
-      color-scheme: dark;
-    }
-    [data-theme="dark"] body {
-      background-color: #121212;
-      color: #e0e0e0;
-    }
-    [data-theme="dark"] .content {
-      background-color: #1e1e1e;
-      box-shadow: 0 2px 10px rgba(0,0,0,0.2);
-    }
-    [data-theme="dark"] .header p {
-      color: #aaa;
-    }
-  </style>
-bodyClass: "no-style-example"
----
-
-<div class="container">
-  <div class="header">
-    <h1>No-Style Page Example</h1>
-    <p>This page demonstrates the no-style feature with a custom layout</p>
-  </div>
-  
-  <div class="content">
-    <h2>What is this page?</h2>
-    <p>
-      This is an example page that uses the <code>noStyle: true</code> frontmatter option to create a completely custom page layout.
-      Unlike regular documentation pages, this page doesn't use the standard docmd layout with sidebar navigation and table of contents.
-    </p>
-    
-    <h2>How does it work?</h2>
-    <p>
-      The <code>noStyle</code> option tells docmd to use a special template that only includes the components you explicitly request
-      via the <code>components</code> object in frontmatter. This gives you complete control over the page structure.
-    </p>
-    
-    <h2>Features enabled on this page:</h2>
-    <ul>
-      <li><strong>meta</strong>: Meta tags, title, and description for SEO</li>
-      <li><strong>favicon</strong>: The site favicon</li>
-      <li><strong>css</strong>: Basic CSS for markdown content</li>
-      <li><strong>theme</strong>: Theme support for light/dark mode</li>
-      <li><strong>scripts</strong>: JavaScript for functionality</li>
-    </ul>
-    
-    <h2>Custom styling</h2>
-    <p>
-      This page includes custom CSS in the <code>customHead</code> frontmatter field. This allows you to define page-specific styles
-      without affecting the rest of your site.
-    </p>
-    
-    <a href="/content/no-style-pages/" class="button">Get Back to No-Style Pages Documentation</a>
-  </div>
-</div> 

package/docs/content/no-style-pages.md

@@ -1,226 +0,0 @@
----
-title: "No-Style Pages"
-description: "Create custom standalone pages with minimal styling and only the components you need."
----
-
-# No-Style Pages
-
-docmd offers a "no-style" page format that gives you maximum flexibility to create custom standalone pages while still leveraging the docmd infrastructure. This is perfect for creating:
-
-- Landing pages with custom layouts
-- Welcome pages with unique designs
-- Single-page websites
-- Special marketing pages
-- Any page that needs a completely custom design
-
-## How It Works
-
-To create a no-style page, add `noStyle: true` to your page's frontmatter. This tells docmd to use a special template that only includes the components you explicitly request.
-
-By default, a no-style page will render just your content with minimal HTML structure. **All components are disabled by default** and must be explicitly enabled via the `components` object in frontmatter.
-
-> **Note:** This behavior changed in v0.2.0. Previously, some components were enabled by default and had to be disabled. Now all components are opt-in only.
-
-## HTML Support
-
-No-style pages fully support raw HTML content without any escaping or processing. You can write pure HTML in your markdown files, and it will be rendered exactly as written. This gives you complete control over the page structure and design.
-
-Unlike regular markdown pages, where HTML might be processed or escaped, no-style pages treat your content as raw HTML, making them perfect for custom layouts and designs.
-
-## Basic Example
-
-Here's a minimal example of a no-style page:
-
-```yaml
----
-title: "Welcome"
-description: "Welcome to my project"
-noStyle: true
-components:
-  meta: true  # Include meta tags, title, description
-  # css: false  # Not needed - CSS is disabled by default
----
-
-<div style="text-align: center; padding: 50px;">
-  <h1>Welcome to My Project</h1>
-  <p>This is a completely custom page with only the components I need.</p>
-  <a href="/docs/" class="button">View Documentation</a>
-</div>
-```
-
-## Available Components
-
-You can control exactly which components are included in your page by setting them to `true` in the `components` object. **All components are disabled by default** and must be explicitly enabled:
-
-| Component | Description | Required Setting |
-|-----------|-------------|------------------|
-| `meta` | Meta tags, title, description | `meta: true` |
-| `siteTitle` | Include site title after page title | `siteTitle: true` |
-| `favicon` | Include favicon | `favicon: true` |
-| `css` | Include main CSS | `css: true` |
-| `highlight` | Include syntax highlighting CSS | `highlight: true` |
-| `theme` | Include theme-specific CSS | `theme: true` |
-| `themeMode` | Include theme mode toggle functionality | `themeMode: true` |
-| `customCss` | Include custom CSS files from config | `customCss: true` |
-| `pluginStyles` | Include plugin-specific CSS | `pluginStyles: true` |
-| `pluginHeadScripts` | Include plugin scripts in head | `pluginHeadScripts: true` |
-| `layout` | Use main content layout (`true`, `'full'`, or `false`) | `layout: true` or `layout: 'full'` |
-| `sidebar` | Include sidebar | `sidebar: true` |
-| `header` | Include page header | `header: true` |
-| `pageTitle` | Include page title in header | `pageTitle: true` |
-| `footer` | Include page footer | `footer: true` |
-| `branding` | Include docmd branding in footer | `branding: true` |
-| `logo` | Include logo in sidebar | `logo: true` |
-| `navigation` | Include navigation in sidebar | `navigation: true` |
-| `themeToggle` | Include theme toggle button | `themeToggle: true` |
-| `toc` | Include table of contents | `toc: true` |
-| `scripts` | Enable script loading (required for other script components) | `scripts: true` |
-| `mainScripts` | Include main JavaScript (copy code, theme toggle, etc.) | `mainScripts: true` |
-| `lightbox` | Include image lightbox functionality | `lightbox: true` |
-| `customJs` | Include custom JS files from config | `customJs: true` |
-| `pluginBodyScripts` | Include plugin scripts at end of body | `pluginBodyScripts: true` |
-
-## Layout Options
-
-The `components.layout` property has three possible values:
-
-- `false` (default): No layout wrapper, just your raw content
-- `true`: Use the main content layout with optional header and footer
-- `'full'`: Same as `true`, a full layout with content area
-
-## Script Components
-
-Script components work in a hierarchical manner:
-
-1. **`scripts: true`** - Enables script loading (required for all other script components)
-2. **`mainScripts: true`** - Includes main JavaScript functionality (copy code, theme toggle, etc.)
-3. **`lightbox: true`** - Includes image lightbox functionality (requires `mainScripts: true`)
-
-**Example:**
-```yaml
-components:
-  scripts: true      # Enable script loading
-  mainScripts: true  # Include main JavaScript
-  lightbox: true     # Include lightbox (requires mainScripts)
-```
-
-## Sidebar Option
-
-If you set `components.sidebar: true`, the sidebar will be included with optional logo, navigation, and theme toggle button.
-
-## Custom HTML in Head and Body
-
-You can also include custom HTML in the head and body sections:
-
-```yaml
----
-title: "Custom Page"
-noStyle: true
-customHead: |
-  <link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;700&display=swap" rel="stylesheet">
-  <style>
-    body { font-family: 'Roboto', sans-serif; }
-  </style>
-customScripts: |
-  <script>
-    document.addEventListener('DOMContentLoaded', () => {
-      console.log('Page loaded!');
-    });
-  </script>
-bodyClass: "landing-page"
----
-```
-
-## Complete Example
-
-Here's a more complete example of a landing page:
-
-```yaml
----
-title: "My Project"
-description: "A powerful tool for developers"
-noStyle: true
-components:
-  meta: true
-  favicon: true
-  css: true
-  theme: true
-  themeMode: true
-  layout: true
-  header: true
-  pageTitle: true
-  footer: true
-  branding: true
-  scripts: true
-  mainScripts: true
-  lightbox: true
-customHead: |
-  <link href="https://fonts.googleapis.com/css2?family=Poppins:wght@400;600&display=swap" rel="stylesheet">
-  <style>
-    body { font-family: 'Poppins', sans-serif; }
-    .hero { text-align: center; padding: 80px 20px; }
-    .cta-button { display: inline-block; padding: 12px 24px; background: #4a6cf7; color: white; 
-                 text-decoration: none; border-radius: 4px; font-weight: 600; }
-  </style>
-bodyClass: "landing-page"
----
-
-<div class="hero">
-  <h1>Welcome to My Project</h1>
-  <p>A powerful tool that helps developers build amazing things.</p>
-  <a href="/docs/" class="cta-button">Get Started</a>
-</div>
-
-<div class="features">
-  <div class="feature">
-    <h2>Easy to Use</h2>
-    <p>Simple API and clear documentation make it easy to get started.</p>
-  </div>
-  <div class="feature">
-    <h2>Powerful</h2>
-    <p>Advanced features for when you need them.</p>
-  </div>
-  <div class="feature">
-    <h2>Flexible</h2>
-    <p>Adapt to your workflow, not the other way around.</p>
-  </div>
-</div>
-```
-
-## HTML and Markdown Mixed Content
-
-No-style pages support both HTML and Markdown content. You can freely mix them in your page:
-
-```markdown
----
-title: "Mixed Content"
-noStyle: true
-components:
-  meta: true
-  css: true
----
-
-<div style="text-align: center">
-  <h1>My Custom Page</h1>
-</div>
-
-## Regular Markdown Heading
-
-This is regular **Markdown** content that will be processed normally.
-
-<div class="custom-section">
-  <h3>HTML Section</h3>
-  <p>This is HTML content within the page.</p>
-</div>
-
-- Markdown list item 1
-- Markdown list item 2
-```
-
-## Best Practices
-
-1. Start with minimal components and add only what you need
-2. Use the `customHead` property for page-specific styles
-3. Consider creating a separate CSS file for your custom pages
-4. Test your page in both light and dark modes if using theme support
-5. Remember that no-style pages still benefit from docmd's plugins (SEO, analytics, etc.) 

package/docs/content/search.md

@@ -1,68 +0,0 @@
----
-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/contributing.md

@@ -1,101 +0,0 @@
----
-title: "Contributing to docmd"
-description: "Learn how you can contribute to the development and improvement of docmd."
----
-
-# Contributing to docmd
-
-Thank you for your interest in contributing to `docmd`! We welcome contributions from the community to help make `docmd` even better. Whether it's reporting a bug, suggesting a feature, improving documentation, or writing code, your help is appreciated.
-
-## How to Contribute
-
-There are many ways to contribute to `docmd`:
-
-*   **Reporting Bugs:** If you find a bug, please open an issue on our [GitHub Issues page](https://github.com/mgks/docmd/issues). Provide as much detail as possible, including steps to reproduce, expected behavior, and actual behavior.
-*   **Suggesting Features:** Have ideas for improvements? Open an issue and describe what you'd like to see.
-*   **Improving Documentation:** The documentation you're reading now (this site itself!) is built with `docmd` and lives in the `docs/` directory of the repository.
-*   **Writing Code:** If you're interested in fixing bugs or implementing new features, read on for development setup instructions.
-
-## Development Setup
-
-To set up `docmd` for local development:
-
-1. **Fork the Repository:**
-   Click the "Fork" button on the [docmd GitHub page](https://github.com/mgks/docmd) to create your own copy.
-
-2. **Clone Your Fork:**
-   ```bash
-   git clone https://github.com/YOUR_USERNAME/docmd.git
-   cd docmd
-   ```
-
-3. **Install Dependencies:**
-   ```bash
-   npm install
-   ```
-
-### Development Workflow
-
-`docmd` uses Node.js and npm.
-
-1. **Make Your Changes:**
-   * Fix bugs or add features in the `/src` directory.
-   * Add or update tests in the `/tests` directory (if applicable).
-   * Update or add documentation in the `/docs` directory to reflect your changes.
-
-2. **Link for Local Testing:**
-   To use your development version of `docmd` as a global command-line tool on your system:
-   ```bash
-   npm link
-   ```
-   This allows you to run `docmd` from any directory and test your changes.
-
-3. **Test Your Changes:**
-   * Run automated tests with `npm test` (if available).
-   * Test your changes by running `docmd build` or `docmd dev` (which will use `docmd` itself to build its own documentation located in `docs/`).
-
-4. **Code Style:**
-   * Follow the existing code style and formatting.
-   * Consider running `npm run lint` to check for style issues (if set up).
-
-### Environment Setup
-
-To enable live change tracking for internal files during development, set the DOCMD_DEV environment variable:
-
-- **Temporarily:** Run `export DOCMD_DEV=true` in your terminal before starting the dev server.
-- **Permanently:** Add `export DOCMD_DEV=true` to your `~/.zshrc` file and run `source ~/.zshrc`.
-
-### Debugging Build Issues
-
-If you are working on the build process and need to see detailed logs about asset processing or minification, you can run:
-
-```bash
-DOCMD_DEBUG=true docmd build
-```
-
-## Pull Request Process
-
-Once you're satisfied with your changes:
-
-1. **Commit Your Changes:**
-   ```bash
-   git add .
-   git commit -m "Brief description of your changes"
-   ```
-
-2. **Push to Your Fork:**
-   ```bash
-   git push origin main  # or the branch you created
-   ```
-
-3. **Submit a Pull Request:**
-   Go to your fork on GitHub and open a pull request to the `main` branch of the original `mgks/docmd` repository. Provide a clear description of your changes.
-
-4. **Code Review:**
-   Maintainers will review your PR and may suggest changes or improvements. Please be responsive to feedback.
-
-## Code of Conduct
-
-Please be respectful and considerate when interacting with others in the project. We aim to foster an inclusive and welcoming community.
-
-Thank you for helping make `docmd` a great tool for documentation!

package/docs/deployment.md

@@ -1,120 +0,0 @@
----
-title: "Deployment"
-description: "Learn how to deploy your docmd-generated static site to various hosting platforms, including GitHub Pages."
----
-
-# Deploying Your docmd Site
-
-Once you've built your documentation site using `docmd build`, the entire static site is generated into the `site/` directory (or your configured `outputDir`). This `site/` directory contains all the HTML, CSS, JavaScript, and assets needed, making it deployable to any static hosting service.
-
-## Building for Production
-
-Before deployment, ensure you build your site in production mode:
-
-```bash
-docmd build
-```
-
-This generates optimized HTML, CSS, and assets ready for production use. In production, `docmd` may:
-- Minify CSS and JavaScript assets (future feature)
-- Optimize HTML output
-
-## Deployment Options
-
-Since `docmd` generates a standard static site, you can use any static hosting service. Here are some popular options:
-
-### GitHub Pages
-
-GitHub Pages is a popular and free way to host static sites directly from your GitHub repository. `docmd` sites are perfectly suited for this.
-
-#### Option 1: Deploy from a Branch
-
-1. **Push your source files and built site to GitHub.**
-2. **Go to your repository settings.**
-3. **Navigate to the "Pages" section.**
-4. **Under "Source", select the branch and directory where your built site is located.**
-
-The simplest approach is to choose one of:
-
-*   **Built site in the `docs/` folder on the main branch:**
-    *   Configure `docmd`'s `outputDir` to be `docs` in your `docmd.config.js` (e.g., `outputDir: 'docs'`).
-    *   Select "Deploy from a branch" → "main" → "/docs"
-
-If you set `outputDir: 'docs'`, your `docmd.config.js` for `docmd` itself (when building its own docs) would look like:
-
-```javascript
-// docmd.config.js for docmd's own docs, deploying from /docs on main
-module.exports = {
-  siteTitle: 'docmd Docs',
-  srcDir: 'documentation', // Assuming actual source MD files are NOT in the output 'docs'
-  outputDir: 'docs',
-  // ... other config ...
-};
-```
-
-#### Option 2: GitHub Actions (Recommended)
-
-The most robust and automated way to deploy to GitHub Pages is using a GitHub Actions workflow. This workflow will run `docmd build` and then deploy the resulting `site/` directory.
-
-Create a file at `.github/workflows/deploy-docs.yml` with the following content:
-
-```yaml
-name: Deploy docmd docs to GitHub Pages
-
-on:
-  push:
-    branches: ["main"]  # Your default branch
-  workflow_dispatch:   # Allows manual workflow trigger from Actions tab
-
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
-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'
-          cache: 'npm'
-
-      - name: Install docmd (globally or from devDependencies)
-        run: npm install -g @mgks/docmd
-
-      - name: Build site with docmd
-        run: docmd build # Assumes docmd.config.js is in the root and correctly points to srcDir/outputDir
-
-      - name: Setup Pages
-        uses: actions/configure-pages@v5
-
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: ./site # This should be your outputDir path
-
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
-```
-
-Then:
-1.  **Enable GitHub Pages in your repository settings**, selecting "GitHub Actions" as the source.
-2.  **Push the workflow file to your repository**.
-3.  On the next push to `main` (or if you manually trigger the workflow), the Action will run, build your `docmd` site, and deploy it. The URL will be something like `https://YOUR_USERNAME.github.io/YOUR_REPOSITORY/`.
-
-### Other Hosting Options
-
-* **Netlify, Vercel, Cloudflare Pages** - Upload or connect your Git repository and set the build command to your npm script that runs `docmd build`.
-* **Any Web Server** - Simply upload the contents of the `site/` directory to any web server that can serve static files.
-
-By following these guidelines, you can easily get your `docmd`-powered documentation online and accessible to your users.