Turn a README into a web page

The best document your project has is sitting in the repo, rendered as an afterthought.

# The README outgrew the repo

A good README is a real document — it explains, it argues, it teaches. But its natural habitat renders it as an afterthought: plain styling, no math, diagrams as linked images, and a share experience that wraps repository chrome around your words. When you want someone to read the README — a user, a reviewer, a launch thread — you want the document, not the repo page.

Publish it on lucid.page and the same Markdown becomes a typeset page: syntax highlighting, KaTeX math, Mermaid diagrams, and a share card with the title and reading time.

# Publish it from the pipeline

READMEs change when the project changes, so publishing should ride along with the work. A single POST refreshes the page at the same URL — a CI job can re-publish on every push to main:

jq -n --rawfile md README.md '{markdown: $md}' | curl -X POST https://lucid.page/your-page \
  -H "Authorization: Bearer $LUCID_API_KEY" \
  -H "Content-Type: application/json" \
  -d @-

# One link per project, chapters when it grows

A README is a page; the docs around it can be a bundle — getting-started, API notes, FAQ as chapters under one durable link. The page stays unlisted until you say otherwise, and the raw Markdown is always at /raw/ for anything that wants to consume it as text.

# Common questions

# Can I keep the page in sync with my repo?

Yes — updating a page is a single HTTP call, so CI can refresh it on every push. The URL never changes, and previous versions are kept as revisions.

# What happens to relative links and images?

They render as written, so point links and images at absolute URLs before publishing.

# Can I publish a whole docs folder, not just the README?

Yes. Publish each file as a page, then bind them into a bundle — a book with a landing page and chapter navigation.