release

BareProxy Adds Markdown Serving That Turns Markdown Files Into Web Pages With No Build Step

BareProxy 0.14.0 is out with its twelfth plugin, Markdown serving. It’s the third release today. The first two, AI crawler control and bot challenges, were about bots. This one is about pages.

Docs and notes often start out as Markdown. Getting them onto the web usually takes a static site generator and a build step, and then a folder of output that has to match the source. For a dozen pages, that’s a lot of machinery.

With the plugin, BareProxy serves the .md files themselves. Write guide/setup.md and /guide/setup shows it as a web page. Change the file, reload, and the change is there.

The plugin is markdown.wasm on the releases page. Its page on this site has the details, and its manual is in the code repository.

A Folder Becomes a Site

The plugin needs a line to load it and a line that lets it read the folder:

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

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

Now /guide/setup gets guide/setup.md, and /guide/ gets the folder’s index.md, or its README.md when there’s no index. Everything else in the folder, such as pictures and styles, goes out as before.

Links work the way they do on GitHub. A link from one file to another, written as setup.md, points to the page, so a folder of Markdown that works on GitHub works as a site.

The Markdown is CommonMark with GitHub’s additions: tables, task lists, footnotes, strikethrough and alerts such as > [!NOTE]. Headings get ids you can link to. Front matter at the top of a file can set the title and description; without it, the title comes from the first # heading. Pages go out in a plain built-in page that reads well on a phone and in dark mode, or in a template of your own, which is one HTML file with {{title}}, {{toc}} and {{content}} where they belong.

Fast After the First View

Each page is rendered once and kept. On every request the plugin checks the file’s size and the time it last changed. That takes a stat and no read, so an edit shows on the next request while an unchanged page costs next to nothing. A browser that already has the page gets a 304, and the file isn’t even opened.

The check needed something new in BareProxy itself: bareproxy_stat_file, a host function that gives a plugin a file’s size and time of change without opening it. It’s in 0.14.0 for any plugin to use.

Markdown for AI Agents

A tool or AI agent that asks for text/markdown gets the file as written, at the page’s own URL. Browsers never ask that way, so they keep getting HTML. Every page also points to its Markdown in a Link header. Agents would often rather read Markdown than HTML, and this spares them taking a page apart to get back to it.

Built for Odd Files

By default, BareProxy gives a plugin 5 milliseconds for each call on a request. A Markdown file’s size says little about how long it takes to render, though: 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 takes a few milliseconds.

A file over the size limit (512 KB unless the config says otherwise) gets an error page and a note saying why. A file whose rendering brings its instance down is marked and left alone until it changes. BareProxy starts a new instance, so one bad file can’t take the site with it.

Building the plugin also turned up a bug in BareProxy’s shared data, which counted a key again every time it was written. AI crawler control rewrites the same keys every five seconds, so after some weeks its writes would have been refused. That’s fixed in 0.14.0 as well.

Where It Fits

BareProxy’s core already serves a folder as a site, and now the folder can hold Markdown as well as HTML. That suits docs and project pages. Every .md file in the folder is public, as a page and as Markdown, so drafts belong somewhere else. A full blog with feeds and tag pages is still a job for a generator such as Hugo, and BareProxy serves its output as it is.

Next

Plugin 13 came out the same day: cookie consent, in BareProxy 0.15.0. Uptime checks and status pages are next. The full order is on the roadmap.