docs: split the reference out of the README into docs/ - #8
Merged
Conversation
mschmicking
force-pushed
the
docs-restructure
branch
3 times, most recently
from
August 8, 2026 08:26
09cafcc to
01ec1a6
Compare
The README was 353 lines, 219 of them a single API code block. That block was
also the worst part of it: one continuous listing of JSDoc comments, which
cannot be linked to, scanned, or read on a phone.
Splits it into docs/ and rewrites the reference as real prose with per-method
sections, grouped by what you are trying to do rather than by declaration order.
Adds the type-conversion tables and the stack-index rules, which were previously
only discoverable by reading the tests.
docs/api.md full reference, with its own table of contents
docs/migrating-to-2.0.md the breaking-changes table and what to check
docs/troubleshooting.md build failures, including the Windows node-gyp and
npm-12-blocks-scripts cases users will actually hit
docs/development.md layout, CI, and the release process
README keeps what someone needs to decide whether to use this and get it
running: what it is, install, quick start, links, caveats. Now 100 lines with a
table of contents.
Documentation links are absolute GitHub URLs so they also work when the README
is rendered on npmjs.com, where relative links break. docs/ is not in the files
allowlist, so the tarball does not grow.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
mschmicking
force-pushed
the
docs-restructure
branch
from
August 8, 2026 08:51
01ec1a6 to
4acfee4
Compare
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 README was 353 lines, 219 of them a single API code block — one continuous listing of JSDoc comments that cannot be linked to, scanned, or read comfortably on a phone.
What moved
docs/api.mddocs/troubleshooting.mddocs/development.mddocs/migrating-to-2.0.mdREADME: 353 → 100 lines, with a table of contents. It keeps only what someone needs to decide whether to use this and get it running: what it is, install, quick start, doc links, caveats, licence.
Not just a move
The API reference was rewritten as prose with per-method sections, so individual methods are now linkable (
docs/api.md#setfieldindex-key-value). Two things that previously existed only in the test suite are now documented:Troubleshooting also now covers npm 12 blocking install scripts, which every user on npm 12 hits and which was documented nowhere.
Verified
docs/is not in thefilesallowlist, so the published tarball does not growStacked on #7
Branched from
docs-single-license, so #7's commit appears here too. Merge #7 first and this reduces to the docs commit alone.🤖 Generated with Claude Code