BareProxy Markdown Serving Plugin: Markdown Files Rendered to HTML With No Build Step

Status: planned, number 12 of 21 in BareProxy’s build order. The plugins are built easiest first, and this one is about two days of coding: a Markdown library, a template and a cache. It comes after the Bot challenges plugin. This post describes what it will do, and it will be updated as it is built.

A lot of writing already lives as Markdown: documentation, notes, a project’s README, a small blog. Putting it on the web usually means a static site generator, a build step, and a folder of output that has to be kept in sync with the source. For a handful of pages that’s more machinery than the job needs.

The Markdown plugin serves .md files as web pages directly. Change a file, reload the page, and it’s there.

What It Will Do

Render on request. A request for /guide/ serves guide/index.md from a folder, turned into HTML on the way out, with headings, lists, tables, code blocks and links.
One template. The page around the content comes from a single HTML template in the folder, so the pages share a look without a theme system.
Cache the result. Each rendered page is kept until its file changes, so a busy page is rendered once, not once per visitor.
Raw when asked. A request for the .md file itself still gets the Markdown, so tools and AI agents that read Markdown get it as written.

The plugin reads the folder through BareProxy’s sandbox: only folders its config names, and only plain files inside them. A config will look something like this:

plugin md /etc/bareproxy/plugins/markdown.wasm
  config /etc/bareproxy/plugins/md.json
  read /var/www/docs

site docs.example.com
  use md
  route /* -> files /var/www/docs

Where It Fits

BareProxy’s core already serves a folder as a site. This plugin makes that folder able to hold Markdown as well as HTML. For a full blog with tags, feeds and archives, a generator such as Hugo is still the better tool, and BareProxy serves its output as it is.

The whole program is on the plugins page.