docs(readme): use an absolute URL for the logo - #62
Merged
Conversation
The logo does not render on either crate's crates.io page. The cause is not a missing file or HTML sanitization: crates.io resolves relative README paths against the directory the crate's README lives in, which is crates/bugwarden/ (and crates/bugwarden-core/), because both crates symlink the root README. So `assets/logo.svg` was baked into the rendered page as https://github.com/plusky/bugwarden/raw/HEAD/crates/bugwarden/assets/logo.svg which is a 404 -- the file is at assets/logo.svg in the repository root. GitHub renders the same README with the repository root as its base, so the relative path resolves there and the logo has always looked fine. One file cannot satisfy both bases, so name the source absolutely. The raw.githubusercontent URL returns 200 and renders on GitHub and crates.io alike, and pinning main rather than a tag means each page shows the current logo. crates.io renders a README once at publish time and serves the frozen HTML, so this cannot repair the pages for 0.1.0 through 0.3.0; it takes effect with the next published version.
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 logo does not render on either crate's crates.io page
(bugwarden,
bugwarden-core), while it has
always rendered correctly on GitHub.
Cause
Not a missing file, and not HTML sanitization — crates.io keeps the
<img>tag. It resolves relative README paths against the directory the crate's
README lives in. Both crates set
readme = "README.md", and both of thoseare symlinks to the root
README.md, so the base becomescrates/bugwarden/rather than the repository root.
assets/logo.svgwas therefore baked intothe published page as:
.../raw/HEAD/crates/bugwarden/assets/logo.svg— what crates.io generated.../raw/HEAD/assets/logo.svg— where the file actually isGitHub renders the same file with the repository root as its base, so the
relative path resolves there. One README, two different bases — no relative
path can satisfy both.
Fix
Name the source absolutely:
Verified 200, and it renders under both renderers.
mainis pinned ratherthan a tag so each page shows the current logo; a tag would freeze every
release page to the logo of its time.
This is the only relative asset reference in the README, and because both
crates share the file, the one change fixes both pages.
Scope limit
crates.io renders a README once at publish time and serves the frozen
HTML from
static.crates.io. This cannot repair the already-published pagesfor 0.1.0–0.3.0; it takes effect with the next published version.
Verification
cargo fmt --check,cargo clippy --workspace --all-targets -- -D warnings,cargo test --workspace --all-targets --locked(357 passed, 0 failed) — allgreen. The rendered-URL claims above were checked against the live
crates.io/api/v1/crates/bugwarden/0.3.0/readmeoutput and by requestingboth GitHub URLs.