Skip to main content

Write library docs

When a library needs a docs site, who reads library docs now, the page structure, what the package itself must explain, and how agents get the docs that match the installed version.

Agents do most of the reading now. People skim, copy code and check what an agent built. Good docs serve both: an agent finds the complete answer on the first page it opens, and a person finds the key facts and working code without reading a tour.

Docs site or README only

A docs site is optional. A small library with a few functions is better served by a good README and doc comments than by a site nobody keeps current. Add a site when people need guides, live examples or a long reference.

A library with a site uses the starter's docs/ folder, built with Ginko Docs and deployed by Vercel, and follows this page. The audit checks it (the docs items).

A library without a site deletes these parts of the starter:

  • the docs/ folder and the docs entry in pnpm-workspace.yaml
  • the docs:dev and docs:build scripts, and the docs:build and agent-docs.mjs calls in build
  • scripts/agent-docs.mjs, the ./agent-docs export, and dist/agent in files
  • the README Agent setup section (agents read the README in node_modules without a pointer), the README's link to the docs domain and images from docs/public/
  • the docs:dev command and the agent-docs lines in AGENTS.md
  • the docs/ ignores in the ESLint config
  • the overrides, allowBuilds entries and auditConfig.ignoreGhsas in pnpm-workspace.yaml that only the docs app needs; keep an entry only if pnpm why still finds the package
  • the homepage field, or point it at the GitHub repository

The starter generator always writes a docs site; delete these parts after generating, then run pnpm install so the lockfile drops the docs app.

The rules below about the package itself, doc comments and error messages apply to every library.

Three readers

ReaderWhat they doWhere they look first
An agent in the user's projectWrites the codeThe installed package: types, doc comments, errors, then the packaged docs
A person who skimsDecides, copies code, checks the agent's resultThe landing page demo, Examples, one reference table
A person with a problemHas an error or a visible symptomA search for the exact error text

Rules

  1. The package is the first doc. An agent that never opens the docs should still write correct code. Every public export, prop and option has a doc comment with its meaning and default, and says when a value cannot change after mount. Every error a user can hit says how to fix it and links to the page that explains it. Defaults work without setup.
  2. Every task page stands alone. An agent fetches one or two pages. A guide shows the result, the complete files, the traps and a way to check it. Code never exists only inside a live demo.
  3. One source per fact. Examples are real files in docs/app/examples/. The page runs them, "show code" shows them, and the agent Markdown contains them as code. Reference tables come from the types where the tooling allows it.
  4. Write the decision and the trap, not a tour. Say when to choose an option, what goes wrong and how to notice it. Drop history and background that nobody acts on.
  5. Error text is the search key. Troubleshooting starts from the exact message or the visible symptom.
  6. Descriptions are for matching. Agents choose a page from its description in llms.txt. Name what the page lets the reader do and the features it covers.
  7. Test docs like code. See Test the docs.

Write in plain, direct English: short sentences, one instruction per sentence, the exact command or value.

Page structure

Every docs site uses the same sections, so people and agents know where to look in any Lupinum library. Start and Reference are always there; add Guides and Help when there is content for them.

SectionPages
StartIntroduction (what it is, a live result, when it fits and when not) · Get started (install, first working result and a check, on one page, ending with where to ask: the Lupinum OSS Discord) · Examples (complete, copyable) · AI coding agents (the Agent setup from the README)
GuidesOne task per page, named by what the reader wants to do ("Share one lightbox", not "Collections"). Each has the result, the complete files, the traps and a check.
ReferenceComponents, composables, options, types, CSS variables. Tables with name, type, default and meaning.
HelpTroubleshooting by error text and symptom · Known constraints · Upgrade (breaking changes per stable major, from the first stable release on; between prereleases the changelog is enough)

There is no Concepts section. Put each explanation in the guide where the reader needs it.

How agents get the docs

ChannelForProvided by
Packaged docs (<package>/agent-docs) and a pointer in the consumer's AGENTS.mdAgents working in a project that installed the package. The docs match the installed version.scripts/agent-docs.mjs and the README Agent setup section (Overview)
/llms.txt, /llms-full.txt, /raw/**.mdAgents that evaluate the library before installing itGinko Docs, automatically
/mcpAgents with an MCP client, on a deployment with a serverGinko Docs

Do not ship a skill for general library knowledge. In agent evaluations an AGENTS.md pointer to the docs beats a skill clearly, because agents often do not invoke a skill on their own (Vercel, 2026). A skill fits only a workflow the user starts on purpose, such as a migration between major versions.

Live examples and other Vue components must turn into real Markdown for agents. Register a serializer with Ginko Docs' registerAgentMarkdownSerializers that writes an example's files as code blocks, and an install block as the literal command. Then check that docs/.output/public/llms-full.txt contains no <example, <pm-install or Component omitted; the audit checks the deployed site (DOC-02).

Test the docs

Before a release that changes the docs a lot:

  1. Write five tasks a typical user gives their agent, for example "show my CMS images in a justified grid with a lightbox".
  2. Let an agent solve each task in a fresh project, with only the packaged docs (node_modules/<package>/dist/agent/) and no web access.
  3. Note for each task whether the first page it read had the complete answer, what it had to guess, and whether its code works.
  4. Fix the docs where it guessed.