plugins

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

Status: built, number 12 of 21 in BareProxy’s build order, and out in BareProxy 0.14.0 as markdown.wasm on the releases page. Its manual is the README in the code repository.

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 straight from the folder. Change a file, reload the page, and the change is there.

What It Does

  • Pages from files. A request for /guide/setup gets guide/setup.md, and /guide/ gets guide/index.md, or README.md when there’s no index. Everything else in the folder, pictures and styles and HTML files, is served as before.
  • GitHub’s Markdown. Tables, task lists, strikethrough, footnotes, alerts such as > [!NOTE], and headings with ids you can link to. Front matter at the top of a file gives the page its title and description.
  • One template. The page around the content comes from one HTML file of your own, with names such as {{title}}, {{toc}} and {{content}}, or from a plain built-in page that reads well on a phone and in dark mode.
  • Links that work. A link from one file to another, as setup.md, points to the page, so a folder of Markdown that links file to file, as on GitHub, works as a site.
  • Rendered once. Each page is rendered once and kept until its file or the template changes. The plugin can tell by the file’s size and time of change, without reading it, and a browser that already has the page gets a quick 304.
  • Markdown for agents. A tool or AI agent that asks for text/markdown gets the file as written, at the page’s own URL. Every page also points to its Markdown in a header.

Here is a config:

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

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

And the plugin’s own, which can be left out:

# md.conf
template .page.html
skip /api/

read lets the plugin read the folder, inside BareProxy’s sandbox. The template is a file in that folder under a hidden name, so the plugin reads it and visitors never get it.

Built for Odd Files Too

BareProxy gives a plugin 5 milliseconds for its work on a request, and a Markdown file’s size says little about how long it takes to render: a few kilobytes of quotes nested inside quotes take longer than a hundred of plain text. So pages render in BareProxy’s timer calls, which may run for a second, a millisecond after the request comes in. A typical page renders in a few milliseconds. A file too big for its setting gets an error page with a note saying why, and a file that brings its instance down is left alone until it changes, so one bad file can’t keep the site down. The tests run all of these cases inside BareProxy.

Building it turned up two things in BareProxy itself, both in 0.14.0: a new host function that gives a file’s size and time of change without opening it, and a fix for shared data, which counted a key again each time it was written.

Where It Fits

BareProxy’s core already serves a folder as a site. This plugin lets that folder 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.

Every page served, rendered or sent as Markdown carries a note in the request’s record, and status counts them.

The whole program is on the plugins page.