Render Markdown to a docs site

Deploy a folder of Markdown and flypod turns it into a styled HTML docs site:

npx flypod ./docs

The rule

flypod renders Markdown only when the deployed folder has no root index.html. It picks up .md, .markdown, and .mdx files and converts them to HTML using GFM (GitHub Flavored Markdown, via marked).

What you get

• Multiple docs → a navigation sidebar linking every page.
• A README or index file becomes the home page.
• Each page's title is its first # H1; if there is none, flypod prettifies the filename.
• The raw Markdown is still served at its own path as text/markdown, so the source stays fetchable.

Example

A folder like this:

docs/
  README.md        # → home page
  install.md       # → /install
  api.md           # → /api

deploys to a docs site whose home is README.md, with install and api in the sidebar. A page that starts with # Installing flypod gets the title "Installing flypod"; a file named getting-started.md with no H1 gets "Getting Started".

Agents get Markdown, browsers get HTML

Every rendered page is available in two representations at the same URL: the styled HTML a browser sees, and the raw Markdown source an AI agent would rather read. flypod picks between them per request using standard HTTP content negotiation — no separate URL, no config.

An agent that sends Accept: text/markdown gets the Markdown back:

curl -H "Accept: text/markdown" https://<your-site>.flypod.dev/install

HTTP/1.1 200 OK
Content-Type: text/markdown; charset=utf-8
Vary: Accept
X-Markdown-Tokens: 214

• The Accept header decides. Accept: text/markdown (ranked at or above text/html) returns Markdown; a browser's HTML-preferring Accept always returns HTML. This is the same 27-year-old mechanism every HTTP client already speaks, and the convention coding agents like Claude Code use.
• Known AI crawlers (GPTBot, ClaudeBot, PerplexityBot, and friends) get Markdown even without an Accept header — cleaner input for them, unchanged pages for everyone else.
• X-Markdown-Tokens gives an agent a rough token estimate up front so it can budget its context window before reading the body.
• Vary: Accept is set on every response, so caches never hand a browser the Markdown or an agent the HTML.

The home page (/) negotiates too, returning the source of your README/ index doc. This only applies to folders flypod rendered from Markdown — if you ship your own index.html, your HTML is always served as-is, never replaced. You can still fetch any source file directly at its .md path at any time.

When to add an index.html instead

If you want full control over layout (your own HTML, CSS, and routing), ship an index.html and flypod serves your folder verbatim. See Deploy a site.

Next steps