ReadMe

Promptfree, for everyone, and the only version there is

Copy the prompt for Claude CodeCopy the prompt for CodexCopy the prompt for Cursor

Copy

Build me developer documentation that replaces ReadMe — and know why this is ALMOST.

The reference and the guides are a fortnight with a static site generator. What is not is **a try-it console that actually calls the API with the reader's own key**, signed in, with their real data. That means a proxy, key management, and CORS handled — and it is the feature that makes documentation feel like a product rather than a page.

STACK
- Astro with Starlight, or Astro from scratch. Do not build a static site generator
- Pagefind for search: indexed at build, searched in the browser, no server and no per-query cost
- Node 20+ with Fastify for the console proxy and the metrics
- SQLite through better-sqlite3
- Caddy in front

THE REFERENCE
- Generated from an OpenAPI document in the repository. Every endpoint gets a page with its parameters, schemas, responses and examples, written once
- If the specification lives with the code, the documentation cannot drift from the API. That is the whole argument for this approach
- Code samples in several languages generated from the same source rather than written by hand
- Versioned as directories with a switcher, a canonical URL pointing at the current version so search engines do not index four copies, and a banner on old versions

THE CONSOLE, WHICH IS THE PRODUCT
- A form built from the schema: types, required fields, enums and defaults respected
- The reader enters an API key once; it is kept in session storage and sent only to the API being called. Never to your documentation server, and never persisted
- Send from the browser where CORS allows. Where it does not, proxy through a small server of your own — and that proxy must refuse private address ranges, be rate-limited, and only forward to the hosts in your own specification. A general-purpose proxy in a documentation site is a request forgery machine
- The response shown with status, headers, timing and a formatted body
- A curl command for every request, matching exactly what was sent
- For a signed-in reader, inject their own key and their own identifiers into every example, so the documentation shows their data. That is what the paid product does and it is a genuine difference — it turns reading into trying

SEARCH
- Pagefind indexes at build time and runs in the browser: no search server, no query cost, fast over thousands of pages
- Headings ranked above body, filters by section and version, a keyboard shortcut, arrows and Enter
- Record what people searched for and especially what returned nothing. That list is your writing backlog and it is the most useful documentation metric there is

WHAT READERS DO
- Page views, time on page, and which endpoints get opened
- Which code language people copy, so you know which samples to keep accurate
- Where the console was used and what failed, which tells you which endpoint's documentation is wrong
- First-party only: path, referrer host, a coarse device bucket and a salted visitor hash. No cookie, no third party

THE PAGE
- Server-rendered or static, under 100KB, no framework at runtime
- A self-hosted variable font, never one from a CDN
- Dark and light, both measured for contrast
- Code blocks with build-time highlighting, a copy button, filename labels and line highlighting
- Open Graph tags and a generated share image, JSON-LD, a sitemap, canonical URLs, and an llms.txt
- An edit-this-page link straight to the file, which is how a typo gets fixed by whoever found it
- Every code sample compiled or run in CI. A documentation site full of examples that no longer work is worse than none

OPERATIONS
- Built in CI on every merge and deployed as static files; the console proxy is the only server component
- .env for the proxy: BASE_URL, ALLOWED_API_HOSTS, RATE_LIMIT
- A link checker in CI so a dead link fails the build
- Health endpoint

WHAT MATTERS MOST
Generation from the specification, and the console proxy's host allow-list. The first is the difference between documentation and a website; the second is the difference between a helpful feature and a hole in your network.