docs: make the README's links absolute so they work on PyPI - #97
Merged
Conversation
`readme = "README.md"` in pyproject.toml, so this file is the package's long_description and PyPI renders it. Relative links there resolve against pypi.org, which has no `docs/` tree — every documentation link on the project page was dead. Rendered through `readme_renderer`, exactly as PyPI does, 13 relative hrefs survived into the published HTML. The in-page anchor was a 14th: the renderer emits no heading ids at all (0 of them, measured), so `#let-an-ai-assistant- do-it-mcp` went nowhere. Documentation pages point at Read the Docs rather than GitHub blobs — a reader arriving from PyPI gets the rendered site instead of raw Markdown, and `docs/contributing.md` and `docs/license.md` include the root files anyway. `en/latest`, not `en/stable`: there is no stable alias configured (404). CONTRIBUTING.md and LICENSE stay on GitHub, which is where you act on them. Only README.md is touched. Relative links inside `docs/` are correct as they are — MyST rewrites `.md` to `.html` when it builds, so they work both on GitHub and on the site, and hardcoding absolute URLs there would break local previews and send a reader on a pinned version to `/en/latest/`. All 18 URLs in the rendered README verified to resolve.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #97 +/- ##
=======================================
Coverage 89.89% 89.89%
=======================================
Files 41 41
Lines 3632 3632
=======================================
Hits 3265 3265
Misses 367 367
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
Reverts one line of the previous commit. The anchor was bundled in because it matched the pattern — a relative link — without weighing that its failure mode is different in kind. A relative *path* on PyPI navigates somewhere wrong: `pypi.org/project/PyMemoryEditor/docs/mcp.md` does not exist. A relative *fragment* whose id is missing is inert — the browser stays where it is. Nothing errors and nothing goes to the wrong place; the click just does not respond. Against that, absolutising it charged the majority of readers: on GitHub the anchor was an in-page jump and became a full navigation to github.com, reloading the same page to reach a section already on screen. So the mild PyPI cost stays, and the GitHub reader keeps the jump.
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 is the package'"'"'s
long_description(readme = "README.md"inpyproject.toml), so PyPI renders it — and relative links there resolve against
pypi.org, which has nodocs/tree. Every documentation link on the projectpage navigates to something that does not exist.
What was measured
Rendering the README through
readme_renderer, the library PyPI uses:documentation table, plus
CONTRIBUTING.mdandLICENSE.After the change: 0 relative paths, and all 18 absolute URLs verified to
resolve.
Choices behind the targets
Documentation → Read the Docs. A reader arriving from PyPI gets the
rendered site rather than raw Markdown.
docs/contributing.mdanddocs/license.mdinclude the root files, so the content matches either way.en/latest, noten/stable— there is no stable alias configured on theproject (it 404s).
CONTRIBUTING.md and LICENSE → GitHub, which is where you act on them.
The in-page anchor stays relative. It was absolutised in the first commit
and reverted in the second: a relative path on PyPI navigates somewhere
wrong, but a relative fragment with no matching id is merely inert — the
browser stays put, nothing errors. Absolutising it would have charged the
majority of readers, turning an in-page jump on GitHub into a full navigation
that reloads the same page.
Scope
Only
README.md. Relative links insidedocs/are correct as they stand:MyST rewrites
.mdto.htmlat build time, so they work both on GitHub andon the site. Hardcoding absolute URLs there would break local previews and
send a reader on a pinned version off to
/en/latest/.