Skip to content

docs: make README robust to npm's renderer - #14

Merged
rohanpoudel2 merged 1 commit into
mainfrom
docs/npm-readme-rendering
Aug 5, 2026
Merged

docs: make README robust to npm's renderer#14
rohanpoudel2 merged 1 commit into
mainfrom
docs/npm-readme-rendering

Conversation

@rohanpoudel2

Copy link
Copy Markdown
Owner

Follow-up to #13. npmjs.com sanitizes README HTML more aggressively than GitHub does, and for a published package the npm page is where most people meet the project. Two constructs in the new README depended on HTML surviving.

Changes

Dropped the <sup>-based footnote marker on --to. If npm strips <sup>, the dagger disappears and the note below the table loses its referent, leaving an orphaned sentence. It is now a plain bolded lead-in that reads correctly whether or not the tag renders.

Renamed "The --json contract" to "JSON output contract". Backticks in a heading slug to a triple dash (#the---json-contract), which is renderer-dependent. The plain heading is stable across GitHub, npm, and anything else.

Deliberately kept

<div align="center"> on the header and <sub> on the demo caption. If those tags are dropped the content still renders — left-aligned and full-size — so nothing is lost. They degrade rather than break.

Verification

  • All 22 TOC anchors resolve against GitHub's slug algorithm, no duplicate slugs (checked with a script, not by eye).
  • Both relative link targets, ./LICENSE and ./MIGRATION.md, exist in the repo — which is what npm rewrites relative links against, via the repository field.
  • prettier --check passes.

Note, not addressed here

MIGRATION.md is not in the files array, so it is not in the published tarball. The npm page link still works (npm rewrites it to the GitHub repo), but the link is dead for anyone reading the README from node_modules. Adding it to files would fix that; left out of this PR since it changes published package contents.

npmjs.com sanitizes README HTML more aggressively than GitHub does, and
the package page is where most people meet this project.

- Drop the <sup>-based footnote marker on --to. If npm strips <sup>, the
  dagger disappears and the note below the table loses its referent. It
  is now a plain bolded sentence that reads correctly either way.
- Rename "The `--json` contract" to "JSON output contract". Backticks in
  a heading slug to a triple dash (#the---json-contract), which is
  renderer-dependent; the plain heading is stable everywhere.

Kept the centered header and <sub> caption: if those tags are dropped the
content still renders, just left-aligned and full-size, so no information
is lost.

Verified: all 22 TOC anchors resolve against GitHub's slug algorithm with
no duplicate slugs, and both relative link targets (./LICENSE,
./MIGRATION.md) exist in the repo, which is what npm rewrites against.
@rohanpoudel2
rohanpoudel2 merged commit 057d295 into main Aug 5, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant