# 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](https://deweydocs.com/docs/overview)

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](https://deweydocs.com/docs/quickstart).

## Write the task once

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

````md
---
kind: guide
title: Print the retry budget
description: Run a local command and inspect its attempt limit.
---

# Print the retry budget

Install Bun, then run this command from the project root.

```sh
bun 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:

```sh
bunx dewey build
bunx dewey check
```

For this example, the build creates these content files:

```text
.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:

```sh
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](https://deweydocs.com/docs/cli)

## 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:

```md
- [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`.