MarqueDown

This website is powered by MarqueDown, a lightweight site engine written in C++17 by Privateer Systems. The name is a play on Markdown (MD) (which is a lightweight plain-text formatting language that uses simple symbols to structure text—such as headings, lists, links, and emphasis - so it can be easily converted into formatted documents like HTML), our dynamic version which is assembled at the webserver, and letters of Marque which were Privateering licences.

How it works

Content is authored in Markdown and stored in a git repository. MarqueDown polls the repository, rebuilds when it detects new commits, and renders pages through HTML templates (typically in under a millisecond per page) into an in-memory cache. Requests are served directly from cache via FastCGI — the serve path is a hash table lookup returning a pointer to the pre-rendered HTML, typically completing in under a microsecond.

There is no database, no CMS, and no JavaScript framework. Pages are pre-rendered at build time and served instantly from memory.

Features

• Markdown with includes — pages can pull in shared text blocks, reducing repetition across the site
• Template inheritance — a base layout is extended by specialised templates for blog posts, listings, and other page types
• Navigation menus — defined in a simple text file with nested includes; the current page is automatically highlighted
• Blog listings — a directory of Markdown files becomes a date-sorted blog with thumbnail images, summaries, and RSS feed
• Image pipeline — source images are automatically resized into multiple widths with responsive srcset attributes
• Git integration — the engine polls a remote repository and rebuilds the cache when new commits are detected
• Live preview — a built-in development server watches for file changes and refreshes the browser automatically and a VSCode Extension makes life easy

Performance

MarqueDown is single-threaded by design. Git checks happen between requests, never mid-render. A full site rebuild typically completes in under 100 milliseconds for 30 pages.

To put this in context: a typical WordPress page request involves PHP execution, multiple database queries, and plugin hooks — often taking 200-500ms even with caching plugins. A static site generator like Hugo or Jekyll eliminates the runtime cost but still requires a separate build step and a web server to read files from disk on every request. MarqueDown sits between the two: content is dynamic (edit, push, and it rebuilds automatically) but serving is faster than static files because the HTML never touches the filesystem — it goes straight from memory to the socket.

The entire engine runs comfortably on a low-power ARM board with 8 GB of RAM, serving this site alongside other services. The memory footprint for this site (34 cached pages including blog posts, RSS, and sitemap) is under 5 MB resident — most WordPress plugins alone use more than that.

Static assets (CSS, images, fonts) are served directly by Apache. MarqueDown handles only the dynamic page rendering through a Unix socket.

Architecture

MarqueDown runs behind Apache with mod_proxy_fcgi and Cloudflare. The stack is minimal:

• Content — Markdown files in a Forgejo git repository
• Engine — MarqueDown FastCGI process rendering from cache
• Web server — Apache serving static files and proxying dynamic requests
• CDN — Cloudflare for TLS, caching, and DDoS protection

Markdown formatting

MarqueDown uses GitHub Flavoured Markdown (cmark-gfm) with these extensions:

Template and include syntax

Front matter

Each page starts with YAML-style metadata:

---
title: Page Title
date: 2026-03-14
template: blog_post
summary: Short description for listings and RSS.
image: thumbnail.jpg
---

The title, summary, and any custom fields become template variables. template selects which HTML template to render through (defaults to base). date is used for blog sorting. image provides a thumbnail for blog listings.

Auto-generated variables available in templates: {{content}} (rendered page body), {{year}} (current year), {{menu}} (navigation HTML), {{performance}} (render time).

Image pipeline

Source images placed in _images/ are automatically resized to multiple widths (300px, 600px, and full size) and written to static/img/ with responsive srcset attributes. Supported formats: JPEG, PNG, and GIF.

Generated pages

• /feed.xml — RSS feed built from blog posts (requires site_url in config)
• /sitemap.xml — sitemap of all pages with last-modified dates
• Custom 404 — if pages/404.md exists, it is served for missing pages

Redirects

A _redirects file maps old URLs to new ones with 301 permanent redirects:

/old-wordpress-url    /new-page
/2024/03/legacy-post  /blog/2024-03-15-new-post

Safety

All recursive expansion paths are protected against runaway loops:

• Markdown includes (<<file>>) — canonical path stack detects cycles (A includes B includes A), with a hard depth limit of 32 levels
• Template extends ({{extends parent.html}}) — name stack detects inheritance cycles across template chains
• Template includes ({{include file.html}}) — shares the extends stack so cross-cutting cycles between extends and includes are also caught, with a depth limit of 16 levels
• Menu includes — same canonical path stack and depth limit as Markdown includes

If a cycle or excessive depth is detected, the engine returns a clear error identifying the offending file rather than looping indefinitely.

Why not WordPress?

This site was previously a WordPress installation. MarqueDown replaces it with something simpler, faster, and more secure:

• No PHP, no MySQL, no plugins, no updates
• No attack surface beyond Apache and a single compiled binary
• Content versioned in git with full history
• Pages served from memory in microseconds
• The entire site is a handful of Markdown files anyone can edit

This epitomises our approach to engineering. Efficient, secure, simple.