Static site generators have become the default choice for developer blogs, documentation sites, and marketing pages. Tools like Hugo, Jekyll, and Eleventy are powerful, but they come with their own learning curves, plugin ecosystems, and configuration overhead. Sometimes you just want to turn a folder of Markdown files into a website.

In this guide, we will build a minimal static site generator from scratch using the DocForge API as the Markdown-to-HTML conversion engine. The result is a tool you fully control with under 200 lines of code, no Markdown parsing libraries, and no configuration files to manage.

Why Build Your Own SSG?

Before we start, it is worth asking: why build a custom SSG when mature tools already exist? There are several practical reasons:

Project Structure

Our SSG will follow a simple convention. Markdown files live in a content/ directory. Each file includes YAML frontmatter at the top for metadata. The build script reads every Markdown file, extracts the frontmatter, sends the Markdown body to the DocForge API, wraps the resulting HTML in a template, and writes the output to a dist/ directory.

Directory Layout 
my-site/
  content/
    index.md
    about.md
    blog/
      first-post.md
      second-post.md
  templates/
    base.html
  dist/              # generated output
  build.js           # or build.py

A sample Markdown file with frontmatter looks like this:

content/blog/first-post.md 
---
title: My First Post
date: 2026-02-28
description: A short introduction to the site.
tags: [intro, hello]
---

# Welcome to My Blog

This is the **first post** on my new site.

## What to Expect

I will be writing about:

- Web development
- API design
- Static site generation

Stay tuned for more content.

Parsing Frontmatter

Frontmatter is the block of YAML at the top of a Markdown file, delimited by triple dashes. We need to separate it from the Markdown body before sending the body to the API. This is a straightforward string operation that does not require a YAML library for simple key-value metadata.

JavaScript Implementation

JavaScript 
function parseFrontmatter(fileContent) {
  const match = fileContent.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
  if (!match) {
    return { metadata: {}, body: fileContent };
  }

  const rawMeta = match[1];
  const body = match[2];
  const metadata = {};

  for (const line of rawMeta.split('\n')) {
    const colonIndex = line.indexOf(':');
    if (colonIndex === -1) continue;
    const key = line.slice(0, colonIndex).trim();
    let value = line.slice(colonIndex + 1).trim();

    // Handle simple arrays like [tag1, tag2]
    if (value.startsWith('[') && value.endsWith(']')) {
      value = value.slice(1, -1).split(',').map(v => v.trim());
    }

    metadata[key] = value;
  }

  return { metadata, body };
}

Python Implementation

Python 
import re

def parse_frontmatter(file_content):
    match = re.match(r"^---\n(.*?)\n---\n(.*)$", file_content, re.DOTALL)
    if not match:
        return {}, file_content

    raw_meta = match.group(1)
    body = match.group(2)
    metadata = {}

    for line in raw_meta.split("\n"):
        if ":" not in line:
            continue
        key, value = line.split(":", 1)
        key = key.strip()
        value = value.strip()

        # Handle simple arrays like [tag1, tag2]
        if value.startswith("[") and value.endswith("]"):
            value = [v.strip() for v in value[1:-1].split(",")]

        metadata[key] = value

    return metadata, body

For more complex YAML frontmatter (nested objects, multi-line strings), you could also send the frontmatter block to the DocForge /api/yaml-to-json endpoint to get structured JSON back. This avoids pulling in a YAML parsing library entirely.

Batch Converting Markdown to HTML

The core of our SSG is a loop that reads every Markdown file, parses its frontmatter, and sends the body to the DocForge API. We will process files concurrently to keep build times fast.

JavaScript (Node.js)

JavaScript 
import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
import { join, dirname, relative } from 'node:path';

const API_URL = 'https://docforge-api.vercel.app/api/md-to-html';
const CONTENT_DIR = './content';
const DIST_DIR = './dist';

async function convertMarkdown(markdown) {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ markdown })
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

async function getMarkdownFiles(dir) {
  const entries = await readdir(dir, {
    recursive: true,
    withFileTypes: true
  });
  return entries
    .filter(e => e.isFile() && e.name.endsWith('.md'))
    .map(e => join(e.parentPath || e.path, e.name));
}

async function buildSite() {
  const files = await getMarkdownFiles(CONTENT_DIR);
  console.log(`Found ${files.length} Markdown files`);

  const template = await readFile(
    './templates/base.html', 'utf-8'
  );

  const results = await Promise.all(
    files.map(async (filePath) => {
      const raw = await readFile(filePath, 'utf-8');
      const { metadata, body } = parseFrontmatter(raw);

      // Convert Markdown body via DocForge API
      const { html, meta } = await convertMarkdown(body);

      // Build the output path: content/blog/post.md -> dist/blog/post/index.html
      const relPath = relative(CONTENT_DIR, filePath);
      const slug = relPath.replace(/\.md$/, '');
      const outPath = join(DIST_DIR, slug, 'index.html');

      // Inject content into the HTML template
      const page = template
        .replace('{{title}}', metadata.title || 'Untitled')
        .replace('{{description}}', metadata.description || '')
        .replace('{{date}}', metadata.date || '')
        .replace('{{content}}', html)
        .replace('{{wordCount}}', String(meta.wordCount))
        .replace('{{headings}}', JSON.stringify(meta.headings));

      await mkdir(dirname(outPath), { recursive: true });
      await writeFile(outPath, page);

      return { slug, title: metadata.title, wordCount: meta.wordCount };
    })
  );

  console.log(`Built ${results.length} pages:`);
  results.forEach(r => console.log(`  /${r.slug} — ${r.title} (${r.wordCount} words)`));
}

buildSite();

Python

Python 
import os
import asyncio
import aiohttp
from pathlib import Path

API_URL = "https://docforge-api.vercel.app/api/md-to-html"
CONTENT_DIR = Path("content")
DIST_DIR = Path("dist")

async def convert_markdown(session, markdown):
    async with session.post(
        API_URL,
        json={"markdown": markdown}
    ) as resp:
        resp.raise_for_status()
        return await resp.json()

async def build_page(session, file_path, template):
    raw = file_path.read_text(encoding="utf-8")
    metadata, body = parse_frontmatter(raw)

    # Convert Markdown body via DocForge API
    result = await convert_markdown(session, body)
    html = result["html"]
    meta = result["meta"]

    # Build the output path
    rel_path = file_path.relative_to(CONTENT_DIR)
    slug = str(rel_path.with_suffix(""))
    out_path = DIST_DIR / slug / "index.html"

    # Inject content into the HTML template
    page = (template
        .replace("{{title}}", metadata.get("title", "Untitled"))
        .replace("{{description}}", metadata.get("description", ""))
        .replace("{{date}}", metadata.get("date", ""))
        .replace("{{content}}", html)
        .replace("{{wordCount}}", str(meta["wordCount"])))

    out_path.parent.mkdir(parents=True, exist_ok=True)
    out_path.write_text(page, encoding="utf-8")

    return {"slug": slug, "title": metadata.get("title")}

async def build_site():
    md_files = sorted(CONTENT_DIR.rglob("*.md"))
    print(f"Found {len(md_files)} Markdown files")

    template = Path("templates/base.html").read_text(encoding="utf-8")

    async with aiohttp.ClientSession() as session:
        tasks = [build_page(session, f, template) for f in md_files]
        results = await asyncio.gather(*tasks)

    print(f"Built {len(results)} pages:")
    for r in results:
        print(f"  /{r['slug']} — {r['title']}")

asyncio.run(build_site())

Creating the HTML Template

The template is a standard HTML file with placeholder tokens that the build script replaces. This is where you define your site's visual design, navigation, and layout. Here is a minimal starting point:

templates/base.html 
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{title}}</title>
  <meta name="description" content="{{description}}">
  <style>
    body {
      font-family: -apple-system, sans-serif;
      max-width: 720px;
      margin: 0 auto;
      padding: 40px 20px;
      line-height: 1.7;
      color: #1a1a2e;
    }
    h1, h2, h3 { margin-top: 2em; }
    pre { background: #f5f5f5; padding: 16px; overflow-x: auto; }
    code { font-size: 14px; }
    a { color: #6366f1; }
  </style>
</head>
<body>
  <nav><a href="/">Home</a></nav>
  <article>
    <header>
      <h1>{{title}}</h1>
      <time>{{date}}</time>
      <span>{{wordCount}} words</span>
    </header>
    {{content}}
  </article>
</body>
</html>

You can make the template as elaborate as you like. Add a header, footer, sidebar, dark mode toggle, syntax highlighting CSS, or analytics scripts. The build script simply replaces the placeholder tokens with actual values.

Generating a Table of Contents

The DocForge API returns an array of headings extracted from the Markdown document in the meta.headings field. You can use this to automatically generate a table of contents for each page.

JavaScript 
function buildTableOfContents(headings) {
  if (!headings || headings.length === 0) return '';

  const items = headings
    .map(h => {
      const id = h.toLowerCase().replace(/[^a-z0-9]+/g, '-');
      return `  <li><a href="#${id}">${h}</a></li>`;
    })
    .join('\n');

  return `<nav class="toc">\n  <h2>Contents</h2>\n  <ol>\n${items}\n  </ol>\n</nav>`;
}

Insert the generated TOC into your template by adding a {{toc}} placeholder and replacing it during the build step.

Adding a Blog Index Page

A static site generator is not complete without an index page that lists all blog posts. Since we already have the metadata from each file's frontmatter, we can generate a blog listing page during the build.

JavaScript 
function buildBlogIndex(pages) {
  // Sort by date, newest first
  const sorted = [...pages]
    .filter(p => p.slug.startsWith('blog/'))
    .sort((a, b) => new Date(b.date) - new Date(a.date));

  const items = sorted.map(p => `
    <article>
      <time>${p.date}</time>
      <h2><a href="/${p.slug}">${p.title}</a></h2>
      <p>${p.description}</p>
      <span>${p.wordCount} words</span>
    </article>`).join('\n');

  return `<!DOCTYPE html>
<html lang="en">
<head><title>Blog</title></head>
<body>
  <h1>Blog</h1>
  ${items}
</body>
</html>`;
}

Handling Errors and Rate Limits

When processing many files, you should handle API errors gracefully. The DocForge free tier allows 500 requests per day, which is sufficient for most static sites. For larger sites, the Pro tier provides 50,000 requests per day.

JavaScript 
async function convertWithRetry(markdown, retries = 3) {
  for (let attempt = 1; attempt <= retries; attempt++) {
    try {
      const response = await fetch(API_URL, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ markdown })
      });

      if (response.status === 429) {
        // Rate limited — wait and retry
        const wait = Math.pow(2, attempt) * 1000;
        console.warn(`Rate limited. Retrying in ${wait}ms...`);
        await new Promise(r => setTimeout(r, wait));
        continue;
      }

      if (!response.ok) {
        throw new Error(`API returned ${response.status}`);
      }

      return response.json();
    } catch (err) {
      if (attempt === retries) throw err;
      console.warn(`Attempt ${attempt} failed: ${err.message}`);
    }
  }
}

You can also add concurrency limiting so you do not fire off hundreds of requests simultaneously. A simple semaphore pattern with a concurrency of 10 works well for most build scenarios.

JavaScript 
async function withConcurrency(tasks, limit = 10) {
  const results = [];
  const executing = new Set();

  for (const task of tasks) {
    const promise = task().then(result => {
      executing.delete(promise);
      return result;
    });
    executing.add(promise);
    results.push(promise);

    if (executing.size >= limit) {
      await Promise.race(executing);
    }
  }

  return Promise.all(results);
}

Caching for Faster Rebuilds

Converting every Markdown file on every build is wasteful if most files have not changed. A simple content-hash cache can skip files that have not been modified since the last build.

JavaScript 
import { createHash } from 'node:crypto';

const CACHE_FILE = '.build-cache.json';

function hashContent(content) {
  return createHash('sha256').update(content).digest('hex');
}

async function loadCache() {
  try {
    const data = await readFile(CACHE_FILE, 'utf-8');
    return JSON.parse(data);
  } catch {
    return {};
  }
}

async function buildWithCache() {
  const cache = await loadCache();
  const newCache = {};
  let skipped = 0;

  for (const filePath of files) {
    const raw = await readFile(filePath, 'utf-8');
    const hash = hashContent(raw);
    newCache[filePath] = hash;

    if (cache[filePath] === hash) {
      skipped++;
      continue;  // File unchanged, skip conversion
    }

    // Convert and write as before...
  }

  await writeFile(CACHE_FILE, JSON.stringify(newCache, null, 2));
  console.log(`Skipped ${skipped} unchanged files`);
}

Integrating with CI/CD

The final step is running your SSG automatically on every push. Here is a GitHub Actions workflow that builds the site and deploys it to a static hosting provider:

.github/workflows/build.yml 
name: Build and Deploy

on:
  push:
    branches: [main]
    paths:
      - 'content/**'
      - 'templates/**'
      - 'build.js'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Build site
        run: node build.js

      - name: Deploy to hosting
        uses: your-deploy-action
        with:
          publish-dir: ./dist

Because the DocForge API handles all Markdown parsing, your CI environment does not need any special Markdown dependencies. The build script is self-contained.

Advanced: Using YAML-to-JSON for Complex Frontmatter

If your frontmatter includes nested objects, multi-line descriptions, or anchors, the simple regex parser above may not be enough. Rather than installing a YAML library, you can send the frontmatter block to the DocForge /api/yaml-to-json endpoint:

JavaScript 
async function parseComplexFrontmatter(yamlBlock) {
  const response = await fetch(
    'https://docforge-api.vercel.app/api/yaml-to-json',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ yaml: yamlBlock })
    }
  );

  const { json } = await response.json();
  return JSON.parse(json);
}

This gives you a zero-dependency YAML parser that handles every edge case without adding a library to your project.

Performance Results

To give you a sense of real-world build times, here are benchmarks from a test site with 50 Markdown files averaging 800 words each:

These numbers are competitive with local Markdown parsing libraries, and you get the advantage of guaranteed consistent output and zero local dependencies.

Summary

Building a static site generator with the DocForge API is a practical approach when you want full control over your build pipeline without managing Markdown parsing dependencies. The key components are straightforward: read Markdown files, extract frontmatter, send the body to the API, inject the HTML into a template, and write the output.

The DocForge API's sub-50ms response times make it viable for build-time conversion, and the extracted metadata (word count, headings) provides useful data for table of contents generation and blog index pages. Combined with content-hash caching and concurrency limiting, you get fast, reliable builds that work identically in local development and CI/CD environments.

The free tier at 500 requests per day is more than enough for development. For production sites with hundreds of pages, the Pro plan at $9/month covers up to 50,000 conversions per day.

Start Building with DocForge

500 requests/day free. No API key required. Build your SSG in minutes.

Try It Live

Related Articles