docs: make README robust to npm's renderer - #14
Merged
Conversation
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.
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
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.
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
--jsoncontract" 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
./LICENSEand./MIGRATION.md, exist in the repo — which is what npm rewrites relative links against, via therepositoryfield.prettier --checkpasses.Note, not addressed here
MIGRATION.mdis not in thefilesarray, 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 fromnode_modules. Adding it tofileswould fix that; left out of this PR since it changes published package contents.