readmeta --fix: Repair Broken PyPI README Links

Why a README can break on PyPI

Your package README isn't always shown in the same "context" as the files in your repository. On GitHub, a relative reference like docs/shot.png resolves against the repo. PyPI instead displays the package's built long_description, which doesn't automatically share that same repo context. So a link or image that works during development can be dead on the PyPI page.

Common examples include:

• Relative images, like ![Screenshot](docs/shot.png).
• Relative links to docs or files elsewhere in the repository.
• Raw SVG references that don't render correctly once embedded in PyPI.
• Broken heading anchors, where something like #instalation doesn't match any heading ID in the rendered page.

It's easy to miss these because they aren't Python build errors. The package can build successfully while the README is less useful to people trying it out. twine check helps with package metadata, but (per readmeta's project description) it doesn't flag every broken README reference like this.

The practical takeaway: test what you actually plan to publish. Checking only README.md in a browser isn't the same as checking the description embedded in a wheel or source distribution. That difference matters most when the README drives someone's first impression.

What readmeta --fix changes

The --fix option uses findings from readmeta's package check and tries to rewrite supported relative references in the artifact. It doesn't modify your working-tree README, and it doesn't overwrite the artifact you passed in. By default, it writes a corrected copy next to the input; you can also choose an output location with --out-dir.

For GitHub-based references, the v0.2 default mapping is:

• Relative images become raw.githubusercontent.com/<repo>/<ref>/<path>.
• Other relative links become github.com/<repo>/blob/<ref>/<path>.
• The default ref is main. Use --ref if you need a different branch, tag, or ref.

For example, a README reference to docs/shot.png in the octo/demo repository can become https://raw.githubusercontent.com/octo/demo/main/docs/shot.png. If your assets are hosted somewhere else, --base-url lets you resolve the references against a URL you control (like a CDN).

pip install readmeta
python -m build
readmeta check dist/* --fix --repo octo/demo

The command produces fixed artifacts like *.fixed.whl and *.fixed.tar.gz. Upload those outputs - not the original files - if you want the rewritten descriptions to end up in the release:

twine upload dist/*.fixed.*

Easy to overlook: the original wheel or source distribution remains untouched. If you run --fix and then upload the original files, you effectively bypass the correction. Treat the fixed artifact as a deliberate release candidate and make the upload step target it.

readmeta check dist/* --fix \
--repo octo/demo \
--base-url https://cdn.example.com/static/

A practical release workflow

The least painful way to use --fix is as a post-build release step. Build the wheel and source distribution, let readmeta inspect the built artifacts and rewrite supported references, then review what it changed (and what it couldn't), and only then upload the results. This is different from manually editing generated wheel contents. Manual tweaks are hard to reproduce and tend to vanish the next time someone rebuilds.

A basic local workflow looks like this:

python -m build
readmeta check dist/* --fix --repo octo/demo
# Review any reported issues and the generated *.fixed.* files.
twine upload dist/*.fixed.*

If you use a custom asset host, add --base-url. If your release needs to point at a specific versioned repository ref, add --ref. The "right" values depend on how you publish assets - readmeta can't guess what versioned location you intended to ship.

Limits, trade-offs, and review points

--fix is intentionally not a general-purpose README editor. It rewrites supported relative image, link, and raw-SVG findings. It avoids rewriting content inside fenced code blocks, inline code, and <pre> / <code> regions. That distinction matters: examples that demonstrate a broken pattern shouldn't suddenly become live links just because the rest of the document got fixed.

Broken in-page anchors are different. A link like #instalation can't be turned into a valid absolute GitHub URL; there's no safe destination to infer when the matching heading doesn't exist. readmeta reports those as remaining issues for manual correction. Fix the typo, add the intended heading, or remove the link - then rebuild and rerun the check.

The boundary between automatic and manual fixes is a good one. Relative paths can often be resolved once you provide a repository or base URL. A broken anchor needs editorial judgment. If the tool "guessed" a destination, the output might look repaired even when it isn't.

Conclusion

readmeta v0.2 targets a specific release pain: a README can be valid in the repository but broken in what package users actually see on PyPI. Its --fix option keeps your source files untouched, rewrites supported relative references in generated artifacts, and leaves ambiguous cases like broken heading anchors for you to fix.

The workflow is straightforward: build, check the artifacts, review unresolved findings, and upload the fixed copies. Add it to your release process if PyPI README quality matters for your users, and double-check both the generated URLs and your upload glob before relying on it in CI. Start with the readmeta package on PyPI or review the project source on GitHub.