Skip to content

ADR 0126: The docs read the tables

Status

Accepted

Context

The site documented the project and not the editor. Its nav was Spec, Roadmap, Plugins, Extensibility, Feedback, Decisions — every one of them for a contributor or a historian. Nothing told someone who had installed ase how to change the font, pick a theme, or rebind a key.

docs/plugins.md was a placeholder saying the plugin host "isn't wired into the GUI yet (no keybinding or command-palette to trigger a plugin interactively)". That stopped being true at ADR 0054 and again at ADR 0113, which made a plugin command bindable. The same claim was in CONTRIBUTING.md. One site, one placeholder page, and it was already lying in two places.

The question asked was whether user documentation wanted a second site.

Decision

One site, three top-level tabs: Guide, Reference, Project.

A second site would double the theme, the deploy, the domain and the search index, and guarantee drift between them — a project that could not keep one page current had no business maintaining two sites. It would also sever the ADRs from the pages that want to link them: "why is Ctrl+W the prefix" has a considered answer in ADR 0120, and a reader who asks it should land there.

The Reference tab is written by the binary

Three pages — every command, every default binding, every config key — are generated by ase --dump-docs <dir>, which builds a real window and a real buffer and reads:

  • CommandRegistry, for the 43 commands and the descriptions already written for the F1 panel
  • keys::defaults(), the same table the editor dispatches from
  • ase_config_key_docs(), the same table that produces the starter config file

This is the principle the F1 panel already runs on, applied to the site. A hand-written copy of any of these is wrong the first time a command is renamed, and nothing would say so.

The generator refuses rather than writing a short page: a binding matching no layer, or a command matching no group, fails the dump with the name in the message. A page that is quietly missing a row is worse than no page.

Committed, and checked

The generated files are committed, so the docs site builds without Qt. That reintroduces the drift the generator removes, so CI regenerates them in the job that already has a GUI build and fails on any diff.

Verified by adding a binding without regenerating: the check fails and names the files.

Consequences

Nine hand-written Guide pages: install, first five minutes, configuration, themes, keybindings, the command line, Vim mode, language servers, writing a plugin.

Writing them turned up two things the code says and the docs did not. : does not take registry command names — :editor.save reports an unknown command, because runCommand falls through to plugin commands only. And a plugin command discards the buffer's undo history, because the plugin edits underneath the undo stack. Both are now written down; the first is arguably a wart worth fixing rather than documenting.

docs/plugins.md is deleted and CONTRIBUTING.md's stale paragraph now points at the Guide instead of restating it.

md_in_html is added to the markdown extensions, for the cards on the landing page.