docs: restructure the README, split reference material into docs/ - #6
Merged
Conversation
The content was strong but the furniture was missing and the ordering buried the parts people actually open a README for. - badges: CI, latest release, Neovim version, platforms, license. The plugin runs a 3-platform matrix and has a tagged release; none of it was visible. - section nav under the fold, so 300+ lines are scannable. - Configuration promoted from a <details> nested inside Usage to its own top-level section. show_hints and every other option were two levels deep. - new Troubleshooting section, absorbing the platform path table, the CURSOR_CONFIG_DIR / CURSOR_STATE_DB_PATH overrides and cursor_paths.py — all of which were squatting in Requirements. Adds "no suggestions appear" and "<Tab> does nothing", the two most likely first-run failures. - Requirements trimmed to the three things you actually need. - Installation split into lazy.nvim / vim.pack subsections. - documents sidecar_cmd, and that map_partial = false disables it. - beta warning de-duplicated (it was stated twice) and moved to a GitHub admonition. CONTRIBUTING.md is new: bug-report checklist, project layout and the stdio boundary, how to run all five spec invocations locally, PR conventions and commit style, and an explicit scope statement. No content was dropped from the README — everything moved or stayed.
Two fixes on the restructure. show_hints had its own ### heading while five sibling options had nothing — recency bias from having just shipped it, and it implied a hierarchy that isn't real. Configuration is now a flat options table where every option gets equal billing, with show_hints' extra nuance (two surfaces, asymmetric cost of hiding each) folded into a <details> instead of a peer-level section. The ASCII pipeline diagram became mermaid, which GitHub renders natively. The ASCII could only show one direction; the mermaid version shows the round trip — request out, streamed edits and the next-jump target back — and states the boundary that matters: the Lua side never touches the network. Also promoted the tab-tab-tab flow from a prose sentence to its own diagram. It's the signature interaction and the hardest thing to convey in words; the loop back through jump → accept is the whole point and now it's visible. Both diagrams validated through mermaid.ink — they render, and the inline <b>/<code> markup renders rather than leaking as literal tags. Horizontal layout on both: the flow diagram was 841px tall as TD, 272px as LR.
Troubleshooting was the worst offender — "Cursor can't be found", platform path tables and env-var overrides are reference material someone reaches for once, sitting inline in the file every newcomer reads first. Installation was worse by volume: 98 lines, two thirds of it edge cases behind <details>. The rule now: the README pitches, installs, and summarizes. Anything longer than a screen lives in docs/ and is linked from the matching section. README.md 369 -> 243 lines, no section over 35 docs/installation.md vim.pack parity, cmp/blink coexistence, pinning docs/configuration.md per-option reference, incl. which hint to keep docs/troubleshooting.md failure modes, expanded well past what fit inline Splitting docs across files makes link rot silent — a heading rename breaks an anchor that still renders fine and only 404s when a reader clicks. So test/docs_links.py checks every relative link and anchor across all five documents, and runs in CI on all three platforms. Writing it surfaced two real subtleties in GitHub's slug rules, both of which had my checker rejecting correct anchors: code-span contents are escaped, not stripped as markup (`<Tab>` contributes "tab", a real <b> contributes nothing), and consecutive spaces each become their own hyphen rather than collapsing (so "blink.cmp / own" yields a double hyphen). Verified the rendering half against GitHub's own markdown API. Troubleshooting also gained material that never fit inline: a sidecar-startup section keyed on the `last stderr` field, PATH problems under GUI-launched Neovim, `:verbose imap <Tab>` for finding the plugin that stole the key, and a stale-response section pointing at :NeocursorLog. No content dropped — everything moved or stayed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The content was solid; the packaging wasn't. Reference material was inline in the
file every newcomer reads first, and the parts people actually open a README for
were buried.
Structure
The rule: the README pitches, installs, and summarizes. Anything longer than a
screen lives in
docs/, linked from the matching section.README.mddocs/installation.mddocs/configuration.mddebouncegets overridden, which hint surface to keepdocs/troubleshooting.md<Tab>, stale responsesCONTRIBUTING.mdNo README section is over 35 lines now. Troubleshooting went from 50 inline lines
to a 4-line pointer.
Furniture that was missing
runs a three-platform matrix and has a tagged release; none of it was visible.
<details>nested inside Usage. Everyoption was two levels deep, including
show_hints.only draw one direction, so the streamed response was invisible.
hardest thing to convey in prose; the loop back through jump → accept is the
whole pitch.
Troubleshooting gained real material
Things that never fit inline:
PATHproblems under GUI-launched Neovim(
:echo exepath('uv')is empty even when your shell finds it), readinglast stderrwhen the sidecar dies before signalling ready,:verbose imap <Tab>to identify the plugin that took the key, and a stale-response section pointing
at
:NeocursorLog.Link rot is now a CI failure
Splitting docs across files makes broken links silent — a renamed heading
breaks an anchor that still renders fine and only 404s when a reader clicks.
test/docs_links.pychecks all 44 relative links and anchors across the fivedocuments, and runs in the matrix.
Writing it surfaced two GitHub slug rules worth recording, both of which had the
checker rejecting correct anchors:
`<Tab>`contributes
tab; a real<b>contributes nothing.blink.cmp / ownyieldsa double hyphen once
/is dropped.Both verified against GitHub's rendered output rather than assumed — the live
anchor IDs (
letting-nvim-cmp--blinkcmp-own-tab,tab-does-nothing,cursor-cant-be-found) match, as do all seven README nav targets.Accuracy fixes
sidecar_cmddocumented its default asnilwhen it's actually{ "uv", "run", "--with", "httpx[http2]" }, andmap_partial = falsedisablingthe mapping was undocumented.
No content was dropped — 26 distinctive fragments from the pre-split README all
still resolve somewhere. Docs-only: no Lua or Python behavior changes.