Examples

Practical examples showing how to use Docmach for common use cases.

Blog Post with Layout

File: docs/posts/my-first-post.md

<docmach
  type="wrapper"
  file="fragments/blog-layout.html"
  replacement="content"
  params="title: My First Blog Post; author: John Doe; date: 2025-12-07"
>
  # Introduction This is my first blog post using Docmach! ## What I Learned -
  Markdown is powerful - Docmach makes it easy - Custom templates are flexible
</docmach>

Layout: fragments/blog-layout.html

<!DOCTYPE html>
<html>
  <head>
    <title>{{ title }}</title>
    <link rel="stylesheet" href="/styles.css" />
  </head>
  <body>
    <article class="blog-post">
      <header>
        <h1>{{ title }}</h1>
        <div class="meta">
          <span class="author">By {{ author }}</span>
          <time>{{ date }}</time>
        </div>
      </header>
      <div class="content">{{ content }}</div>
    </article>
  </body>
</html>

Dynamic Navigation

Function: fragments/nav.js

export default function (params) {
  const { items = [] } = params;

  return `
    <nav class="main-nav">
      <ul>
        ${items
          .map(
            (item) => `
          <li><a href="${item.link}">${item.text}</a></li>
        `
          )
          .join("")}
      </ul>
    </nav>
  `;
}

Usage in Markdown:

<docmach
  type="function"
  file="fragments/nav.js"
  params="items: {link: /, text: Home}, {link: /about.html, text: About}, {link: /blog.html, text: Blog}"
/>

Auto-Generated Table of Contents

Function: fragments/toc.js

import { readFileSync } from "fs";

export default function (params) {
  const { file } = params;
  const content = readFileSync(file, "utf8");

  // Extract headings
  const headings = [];
  const lines = content.split("\n");

  lines.forEach((line) => {
    const match = line.match(/^(#{2,4})\s+(.+)$/);
    if (match) {
      const level = match[1].length;
      const text = match[2];
      const id = text.toLowerCase().replace(/\s+/g, "-");
      headings.push({ level, text, id });
    }
  });

  // Generate TOC
  return `
    <nav class="toc">
      <h2>Table of Contents</h2>
      <ul>
        ${headings
          .map(
            (h) => `
          <li class="toc-level-${h.level}">
            <a href="#${h.id}">${h.text}</a>
          </li>
        `
          )
          .join("")}
      </ul>
    </nav>
  `;
}

Reading Time Calculator

Function: fragments/reading-time.js

import { readFileSync } from "fs";

export default function (params) {
  const { file, wpm = 200 } = params;
  const content = readFileSync(file, "utf8");

  // Count words
  const words = content.split(/\s+/).length;
  const minutes = Math.ceil(words / wpm);

  return `<span class="reading-time">${minutes} min read</span>`;
}

Author Bio Component

Fragment: fragments/author-bio.html

<div class="author-bio">
  <img src="{{ avatar }}" alt="{{ name }}" class="avatar" />
  <div class="info">
    <h3>{{ name }}</h3>
    <p>{{ bio }}</p>
    <div class="social">
      <a href="https://twitter.com/{{ twitter }}">Twitter</a>
      <a href="https://github.com/{{ github }}">GitHub</a>
    </div>
  </div>
</div>

Usage:

<docmach
  type="fragment"
  file="fragments/author-bio.html"
  params="name: John Doe; bio: Full-stack developer; avatar: /images/john.jpg; twitter: johndoe; github: johndoe"
/>

Code Snippet with Syntax Highlighting

Docmach automatically highlights code blocks:

```javascript
function greet(name) {
  console.log(`Hello, ${name}!`);
}

greet("Docmach");
```

Conditional Content

Function: fragments/conditional.js

<!DOCTYPE html>
<html>
  <head>
    <title>{{ title }}</title>
    <link rel="stylesheet" href="/styles.css" />
  </head>
  <body>
    <article class="blog-post">
      <header>
        <h1>{{ title }}</h1>
        <div class="meta">
          <span class="author">By {{ author }}</span>
          <time>{{ date }}</time>
        </div>
      </header>
      <div class="content">{{ content }}</div>
    </article>
  </body>
</html>
```0

**Usage:**

```html
<!DOCTYPE html>
<html>
  <head>
    <title>{{ title }}</title>
    <link rel="stylesheet" href="/styles.css" />
  </head>
  <body>
    <article class="blog-post">
      <header>
        <h1>{{ title }}</h1>
        <div class="meta">
          <span class="author">By {{ author }}</span>
          <time>{{ date }}</time>
        </div>
      </header>
      <div class="content">{{ content }}</div>
    </article>
  </body>
</html>
```1

## Blog Post List

**Function: `fragments/post-list.js`**

```html
<!DOCTYPE html>
<html>
  <head>
    <title>{{ title }}</title>
    <link rel="stylesheet" href="/styles.css" />
  </head>
  <body>
    <article class="blog-post">
      <header>
        <h1>{{ title }}</h1>
        <div class="meta">
          <span class="author">By {{ author }}</span>
          <time>{{ date }}</time>
        </div>
      </header>
      <div class="content">{{ content }}</div>
    </article>
  </body>
</html>
```2

## Sitemap Generator

**Function: `fragments/sitemap.js`**

```html
<!DOCTYPE html>
<html>
  <head>
    <title>{{ title }}</title>
    <link rel="stylesheet" href="/styles.css" />
  </head>
  <body>
    <article class="blog-post">
      <header>
        <h1>{{ title }}</h1>
        <div class="meta">
          <span class="author">By {{ author }}</span>
          <time>{{ date }}</time>
        </div>
      </header>
      <div class="content">{{ content }}</div>
    </article>
  </body>
</html>
```3

## Breadcrumb Navigation

**Function: `fragments/breadcrumbs.js`**

```html
<!DOCTYPE html>
<html>
  <head>
    <title>{{ title }}</title>
    <link rel="stylesheet" href="/styles.css" />
  </head>
  <body>
    <article class="blog-post">
      <header>
        <h1>{{ title }}</h1>
        <div class="meta">
          <span class="author">By {{ author }}</span>
          <time>{{ date }}</time>
        </div>
      </header>
      <div class="content">{{ content }}</div>
    </article>
  </body>
</html>
```4

## Multi-Column Layout

**Wrapper: `fragments/two-column.html`**

```html
<!DOCTYPE html>
<html>
  <head>
    <title>{{ title }}</title>
    <link rel="stylesheet" href="/styles.css" />
  </head>
  <body>
    <article class="blog-post">
      <header>
        <h1>{{ title }}</h1>
        <div class="meta">
          <span class="author">By {{ author }}</span>
          <time>{{ date }}</time>
        </div>
      </header>
      <div class="content">{{ content }}</div>
    </article>
  </body>
</html>
```5

**Usage:**

```html
<!DOCTYPE html>
<html>
  <head>
    <title>{{ title }}</title>
    <link rel="stylesheet" href="/styles.css" />
  </head>
  <body>
    <article class="blog-post">
      <header>
        <h1>{{ title }}</h1>
        <div class="meta">
          <span class="author">By {{ author }}</span>
          <time>{{ date }}</time>
        </div>
      </header>
      <div class="content">{{ content }}</div>
    </article>
  </body>
</html>
```6

## Alert/Callout Boxes

**Fragment: `fragments/alert.html`**

```html
<!DOCTYPE html>
<html>
  <head>
    <title>{{ title }}</title>
    <link rel="stylesheet" href="/styles.css" />
  </head>
  <body>
    <article class="blog-post">
      <header>
        <h1>{{ title }}</h1>
        <div class="meta">
          <span class="author">By {{ author }}</span>
          <time>{{ date }}</time>
        </div>
      </header>
      <div class="content">{{ content }}</div>
    </article>
  </body>
</html>
```7

**Usage:**

```html
<!DOCTYPE html>
<html>
  <head>
    <title>{{ title }}</title>
    <link rel="stylesheet" href="/styles.css" />
  </head>
  <body>
    <article class="blog-post">
      <header>
        <h1>{{ title }}</h1>
        <div class="meta">
          <span class="author">By {{ author }}</span>
          <time>{{ date }}</time>
        </div>
      </header>
      <div class="content">{{ content }}</div>
    </article>
  </body>
</html>
```8

## Next Steps

- Explore the [API Reference](api-reference.html) for complete documentation
- Check out [Advanced Features](advanced-features.html) for more capabilities
- See the [ROADMAP](../../ROADMAP.md) for upcoming features

<!--DOCMACH_PLACEHOLDER_1-->
<!--DOCMACH_PLACEHOLDER_0-->