📝 docs(migration): order guides by downloads, add npm/crates shields#597
Merged
gaborbernat merged 1 commit intoJul 8, 2026
Merged
Conversation
Reorder the migration-guide toctree by last-month download count, descending, across PyPI, npm, and crates rather than per-namespace adoption. The stdlib parser has no download metric and sorts last. Extend the package-meta directive to render npm and crates badges: the first argument may name the ecosystem, defaulting to PyPI so existing calls are unchanged. npm drops the supported-Pythons badge; crates carries version, license, and downloads. Add the directive to the five non-Python guides (parse5, jsdom, DOMPurify, sanitize-html, lol-html), which had none, fixing the previously badge-less lol-html page.
Merging this PR will not alter performance
Comparing 
Footnotes
|
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 migration-guide index ordered its toctree by per-namespace adoption, so a reader scanning the sidebar saw parse-and-DOM libraries first regardless of how widely each library is used. This orders the whole toctree by last-month download count, descending, across PyPI, npm, and crates, so the guides a reader is most likely to want sit at the top. 📊 The stdlib parser has no download metric, so it sorts last.
The
package-metadirective rendered PyPI shields only, which left the five non-Python guides with no metadata row at all. The directive now takes an optional leading ecosystem argument:npmandcratesrender the shields.io badges for those registries, and a bare package name still means PyPI, so every existing.. package-meta:: <pypi-name>call is unchanged. npm carries version, license, and monthly downloads (there is no supported-Pythons badge); crates carries version, license, and downloads. The optional GitHub slug still adds the stars and last-commit badges for any ecosystem.With that in place, the parse5, jsdom, DOMPurify, sanitize-html, and lol-html guides now open with their npm or crates shields, matching the PyPI guides. This also gives the lol-html guide the metadata row it never had.