Publish Markdown documentation for people and agents from one source

A documentation page and its plain-text version should describe the same behavior. Maintaining separate copies creates another place for a corrected command, changed default, or new limitation to get lost.

Dewey builds the website and its agent-readable copies from the same Markdown. People get an HTML page. An agent can retrieve that page's Markdown, consult an index, or load the full collection. Dewey's document model

This walkthrough uses the outputs of @deweydocs/dewey 0.5.1. It starts after a project's guide and source map have been authored and reviewed using the quickstart.

Write the task once

Consider a small project that prints a configured retry budget. Its guide lives at docs/quickstart.md:

---kind: guidetitle: Print the retry budgetdescription: Run a local command and inspect its attempt limit.---# Print the retry budgetInstall Bun, then run this command from the project root.```shbun run demo```The command prints `Maximum attempts: 5` and exits. It does not send requests.

The guide supplies a prerequisite, an action, and an observable result. Those details are useful to both a person and an agent. There is no need to rewrite this task into a second, abbreviated instruction page.

The source map has a different job. It explains which files implement the behavior, their data flow, and the constraints an agent should preserve while changing them. It stays in the repository.

Build and inspect the results

Run from the initialized project root:

bunx dewey buildbunx dewey check

For this example, the build creates these content files:

.dewey/site/├── index.html├── docs/│   ├── quickstart.html│   └── quickstart.md├── llms.txt├── llms-full.txt└── nav.json

Styles and browser scripts accompany them. The generated HTML contains the guide's title, command, and expected output. The Markdown copy contains the same guide body. Changing the expected output in the source guide and rebuilding updates both destinations.

To inspect the site locally:

python3 -m http.server 4387 \  --bind 127.0.0.1 \  --directory .dewey/site

Open http://127.0.0.1:4387/ for the site and /docs/quickstart.md for the plain-text page. Publish the contents of .dewey/site/ when you are ready to host the generated site. Build outputs

Offer a small index and a full collection

The generated site index includes a short description and size estimate for each page. In the example it contains:

- [Print the retry budget](docs/quickstart.md): Run a local command and inspect its attempt limit. (10 lines, ~48 tokens)

An agent can use that entry to choose a relevant document before retrieving its contents. llms-full.txt provides the guides and references together when the task needs the whole collection. The token figures are estimates, useful for judging relative size.

nav.json exposes the same navigation as structured data: title, summary, HTML path, Markdown path, and source path. It lets a consumer find the text representation without guessing how a human page URL maps to Markdown.

Check the destination of each index before hosting it. The root llms.txt points to repository source files. The version inside .dewey/site/ points to the generated Markdown copies. The site directory is the coherent set of outputs to publish.

Keep implementation maps out of the public collection

Dewey publishes documents with kind: guide and kind: reference. Maps explain source internals; history preserves plans, decisions, and reports. Those two kinds are excluded from the generated site and llms-full.txt.

In the retry example, docs/src.agent.md exists in the repository but its “Retry implementation” content is absent from the full-text site bundle. The public guide explains how to run the command. The map explains how to change its implementation.

Treat this as a publishing rule, not a permission system. Anyone with access to the repository can still read its maps and history.

Maintain the source, then verify the delivery

Edit the Markdown source when a command or expected result changes. Build tracks generated output by hash and refuses a conflicting hand edit rather than quietly replacing it. If a generated page was edited directly, inspect that change, move the intended correction into its source, and resolve the output conflict before rebuilding.

Finish by checking the HTML page, its Markdown copy, and the index link.

These outputs do not guarantee that a search engine or agent will discover, trust, or cite the documentation. Check that a reader can open the guide, retrieve its Markdown, and reproduce Maximum attempts: 5.