---
title: Publishing tools and the choices behind Commons
summary: What we borrowed from Lakebed, Pagecord, Jekyll, MkDocs, and Pagefind, and why the first version stays file based.
owner: Platform
tags:
  - research
  - architecture
---

# Publishing tools and the choices behind Commons

Researched 22 October 2026 for a public company library of Markdown and HTML
files, with a main page, basic search, and a short CLI workflow.

## Lakebed: the workflow reference

Lakebed is a CLI and runtime for small full-stack TypeScript applications.
Its `new`, `dev`, `inspect`, and `deploy` commands make the local-to-hosted
workflow explicit. Commons adopts that clarity and a portable on-disk
contract. Lakebed itself would add application runtime and data services that
this static document library does not need. Its current published limits do
not include custom domains, which also conflicts with `commons.vimaksh.in`.
Sources: [Lakebed documentation](https://docs.lakebed.dev/),
[Lakebed limits](https://docs.lakebed.dev/limits/).

## Other relevant projects

| Project | Useful idea | Our decision |
| --- | --- | --- |
| Pagecord CLI | Publish existing Markdown and HTML files; infer metadata; update the same post later. | Follow the file-first experience while retaining Git ownership and stable document slugs. |
| Jekyll | Both Markdown and HTML can be ordinary pages. | Support both formats without asking every HTML report to become a templated article. |
| MkDocs | Mature Markdown documentation, local preview, and static output. | A strong option for a conventional handbook; this library also needs standalone interactive HTML bundles and import commands. |
| Pagefind | Generate a static search bundle after rendering, with no search server. | Use its separation of content and search as the future indexing boundary. The initial small library uses one JSON index for basic search. |

Sources: [Pagecord CLI](https://help.pagecord.com/pagecord-cli),
[Jekyll pages](https://jekyllrb.com/docs/pages/),
[MkDocs configuration](https://www.mkdocs.org/user-guide/configuration/),
[Pagefind](https://pagefind.app/docs/).

These comparisons describe documented capabilities and our engineering
judgment. We did not benchmark the projects or claim that Commons replaces
their full feature sets.

## What the first version contains

- A small installable Python CLI with explicit import, preview, and publish
  commands. It uses a maintained CommonMark parser rather than inventing a
  Markdown dialect.
- One metadata manifest per document, which avoids a shared hand-maintained
  index file becoming a merge-conflict bottleneck.
- A generated main page, text search, topic and format filters, original
  source downloads, and stable document addresses.
- A host-independent static output directory. Public reading does not
  require the source repository to be public.

No database, server-side document editor, anonymous upload API, semantic
search, or private reading flow is part of v1. Those would be separate product
decisions rather than assumptions hidden inside the publishing standard.

## Hosting and repository migration

The original `rea-canary-defense` repository was renamed to `commons` so the
library can contain work from any team. GitHub redirects repository URLs
after a rename, but project Pages URLs do not receive the same treatment.
The requested stable site address is the custom domain `commons.vimaksh.in`.
Source: [GitHub repository rename behavior](https://docs.github.com/en/repositories/creating-and-managing-repositories/renaming-a-repository).

At implementation time, the source repository was private and its plan did
not support GitHub Pages. The CLI and protocol therefore target a static
build artifact that Cloudflare Pages can publish, rather than requiring a
change in repository visibility. Git-connected hosting needs the Cloudflare
GitHub app to have access to that repository.
Sources: [GitHub Pages availability](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site),
[Cloudflare Git integration](https://developers.cloudflare.com/pages/configuration/git-integration/github-integration/).

The earlier REA research and its original evidence are preserved as one
document in the library.