Skip to content

docs: fix README images that do not render on the API reference site - #38862

Open
dfernaro wants to merge 1 commit into
aws:mainfrom
dfernaro:docs/absolute-readme-image-urls
Open

dfernaro wants to merge 1 commit into
aws:mainfrom
dfernaro:docs/absolute-readme-image-urls

Conversation

@dfernaro

Copy link
Copy Markdown

Issue # (if applicable)

Closes #34023.

Reason for this change

Three README images are referenced by a repository-relative path. That resolves on GitHub, but the API reference site renders the README at a different base URL, so the browser requests the images from a path that does not exist and they silently render as broken.

Confirmed against the live pages:

Reference Requested URL on the docs site naturalWidth
images/ui-screenshot.png https://docs.aws.amazon.com/cdk/api/v2/docs/images/ui-screenshot.png 0
doc-images/unprocessed-template.png https://docs.aws.amazon.com/cdk/api/v2/docs/doc-images/unprocessed-template.png 0
doc-images/processed-template.png https://docs.aws.amazon.com/cdk/api/v2/docs/doc-images/processed-template.png 0

Every other image on those same pages is referenced absolutely and renders correctly, which is the pattern the status badges at the top of every module README already follow.

Description of changes

Point the three references at raw.githubusercontent.com, which serves them as image/png. The image files themselves are unchanged and stay where they are.

These are the only repository-relative image references left in the repo, so no other README is affected:

$ grep -rnP '!\[[^]]*\]\((?!http)[^)]*\.(png|jpg|jpeg|gif|svg)' --include='*.md' packages/
(no matches)

No code block is touched, so Rosetta is unaffected.

One decision worth flagging: the URLs are pinned to main rather than to a commit SHA. That keeps them consistent with how the READMEs already link to other repository content, and lets the images be updated in place, at the cost of breaking if the files are ever moved or renamed. Happy to pin to a SHA instead if you prefer immutability.

An alternative considered and rejected: removing the images altogether. They carry real explanatory value — the cloudformation-include pair shows the exact "View processed template" checkbox state the surrounding prose depends on — so fixing the reference seemed better than dropping the content. Happy to switch to removal if that is the preferred direction.

Describe any new or updated permissions being added

None. This is a documentation-only change.

Description of how you validated changes

No unit or integration tests, as no code changed.

Validated by hand:

  1. Loaded both published documentation pages and inspected every <img>. The three relative references resolve under /cdk/api/v2/docs/ and report naturalWidth === 0; all absolutely-referenced images on the same pages report a non-zero width.
  2. Requested each replacement URL directly and confirmed it is served as image/png with the expected dimensions — 1156×315, 2278×536 and 2280×566 respectively.
  3. Re-ran the repo-wide grep above to confirm no relative image reference remains.

Checklist


By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

Three README images are referenced by a repository-relative path. That
resolves on GitHub, but the API reference site renders the README at a
different base URL, so the browser requests the images from a path that does
not exist and they silently render as broken.

Confirmed against the live pages:

- `images/ui-screenshot.png` on the aws_synthetics page resolves to
  `https://docs.aws.amazon.com/cdk/api/v2/docs/images/ui-screenshot.png`
- `doc-images/unprocessed-template.png` and `doc-images/processed-template.png`
  on the cloudformation_include page resolve to
  `https://docs.aws.amazon.com/cdk/api/v2/docs/doc-images/...`

All three load with `naturalWidth === 0`. Every other image on those pages is
referenced absolutely and renders correctly, which is the pattern the status
badges at the top of every module README already follow.

Point the three references at `raw.githubusercontent.com`, which serves them
as `image/png`. These are the only repository-relative image references left
in the repo, so no other README is affected. No code block is touched, so
Rosetta is unaffected.

One decision worth flagging: the URLs are pinned to `main` rather than to a
commit SHA. That keeps them consistent with how the READMEs already link to
other repository content and lets the images be updated in place, at the cost
of breaking if the files are ever moved or renamed. Happy to pin to a SHA
instead if maintainers prefer immutability.

closes aws#34023

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

beginning-contributor [Pilot] contributed between 0-2 PRs to the CDK effort/medium Medium work item – several days of effort p2

Projects

None yet

Development

Successfully merging this pull request may close these issues.

synthetics/cloudformation_include: screenshot not displayed in documentation

1 participant