DOC-7128 icons-1: render inline UI icons as Markdown images sized by CSS - #4192
Conversation
UI button icons (the #no-click images inside sentences and table cells) were the last image shortcodes the codemod couldn't convert, because Goldmark has no inline attribute syntax to carry their width and class. They now become plain inline Markdown images. render-image.html marks an inline local image img-inline, and one CSS rule sizes it to the surrounding text. This commit adds that mechanism, a --inline-icons codemod mode, the AGENTS.md rule for writing icons, and converts 67 icons in rc/, unversioned rs/, rs/8.0/, and embeds/. The size was tuned in a browser trial with Andy: 1.2em and 1.4em were too small, and 1.5em matched the most common old widths (22-25px). At 1.5em a 24px icon grew its 24px line by 1px, so the rule adds margin: -0.1em 0. The old shortcode icons picked up prose img margins that padded every line or table row holding an icon to 85-104px. The new rule's margin removes that, so icon steps now line up with their neighbors. Two scoping traps. An image alone in a table cell reaches the hook with IsBlock true, the same as a standalone paragraph image, so the hook can't mark it. Cells are matched in CSS by td img[src*="#no-click"] instead. The rule can't be keyed on #no-click alone, though, because 20 standalone #no-click screenshots (a REST API diagram among them) would shrink to text height. The codemod mode converts only #no-click images that aren't their own paragraph, and leaves 35 inline screenshots and 8 info-icon images without #no-click alone. Verified under the production baseURL: every changed image keeps its src, loses its width, gains img-inline (or no class, in a table cell), and keeps its alt or loses only emphasis markers. No image without #no-click gained the class. A scripted browser pass over all 42 affected pages found all 62 rendered icons at exactly 1.5x their text size, and every single-line block at its normal line height. The other 5 icons are in dead embeds that nothing includes. Learned: an image alone in a table cell reaches the image hook with IsBlock true, so cell icons are sized in CSS by td img[src*="#no-click"] Constraint: the icon CSS must not match on #no-click alone; standalone #no-click screenshots would shrink to text height Constraint: --inline-icons converts only #no-click images; inline screenshots without it must stay full size Rejected: 1.2em and 1.4em icon heights | too small in a browser trial with Andy Directive: write a new UI icon as an inline image with #no-click and no attributes; never give a screenshot #no-click inside a sentence Gaps: create-db.md and tls-configuration-procedure.md are included nowhere, so their 5 icons could not be render-verified Ticket: DOC-7128 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
🧠 Redis MemoryFound 8 related items from repository history (3 new this commit):
Memory updated at 35736b7 |
dwdougherty
left a comment
dwdougherty
left a comment
There was a problem hiding this comment.
One comment of my own, and I thought it might be useful for you to see Claude's assessment:
PR #4192: correct and well contained; one image pair is worth changing
This PR differs from the earlier image PRs: besides converting 67 icons in 44 files, it changes the image render hook, adds CSS, extends the codemod, and adds a sentence to AGENTS.md.The changes don't spill onto other pages. Two of the new rules could in principle affect pages beyond these 44 files. I scanned the whole site for both:
The render hook rule shrinks any local image that shares a paragraph with text. No existing Markdown screenshot does that, so nothing new shrinks. My scan flagged one candidate, inside a > [!NOTE] in saml-integration-azure-ad.md, but it's alone in its paragraph there, so the hook leaves it alone.
The table-cell CSS rule (td img[src*="#no-click"]) matches only 7 images on the whole site, all of them in files this PR converts. The unconverted rs/7.22, 7.8, and 7.4 snapshots have no #no-click images in tables, so they don't change before part 2 lands.
All 67 conversions check out. Each line's text is identical apart from the image itself. The image path, including #no-click, is unchanged, and the alt text is unchanged too, with no emphasis lost in practice. The only things dropped are class="inline" (62 icons) and the old widths, which is the intended design. The AGENTS.md sentence is a site-wide rule, so it belongs in the root file.
On the author's "too small?" question:
rc/changelog/april-2025.md is the real concern. The light and dark mode toggle images aren't in a sentence; they form a paragraph of their own. They had no width before, so they rendered at their native 149×57 px. Now they drop to about 63×24 px. I'd put a blank line between them so each becomes a full-size block image, or leave them as shortcodes.
The five icons that were 36px (delete and edit buttons) shrink to 24px, a third smaller. That's probably fine, since most icons were already 22–25px.
The other direction: the two sort arrows grow from 10px to 24px, and node-down-icon.png (natively 16px) is enlarged 1.5×, so it may look slightly soft.
A design suggestion for the review comment: the hook adds img-inline to any local image inside running text, without checking for #no-click. Today that's safe, but in the future a screenshot placed directly under a line of text, with no blank line between, would silently shrink to text height. Requiring both conditions, inline and #no-click, would prevent that. It wouldn't bring back the problem the PR describes, because those 20 #no-click screenshots are block images. The new AGENTS.md sentence already says icons carry #no-click.
| {{< image filename="/images/rs/icon_add.png#no-click" alt="Add button" >}} | ||
|  | ||
|
|
||
| {{< image filename="/images/rs/database-tls-replica-certs.png" alt="Database TLS Configuration" >}} |
There was a problem hiding this comment.
Shouldn't this shortcode instance also be converted?
There was a problem hiding this comment.
Yes, and it is now. That line is a standalone screenshot (database-tls-replica-certs.png, not a #no-click icon), so it's outside this PR's icon conversion, but the default codemod mode converts it. That happened in #4189, which merged after this PR branched off main, so the diff here was still showing the old line as context. I've merged main into this branch (efa4dfe), and line 81 now reads .
(This embed is also one of the dead ones that nothing includes, so it never rendered either way.)
…plit the april-2025 toggles) The hook now marks an image img-inline only when it's inline, local, AND carries #no-click. Before, any local image sharing a paragraph with text qualified, so a future screenshot written directly under a line of text, with no blank line, would have silently shrunk to text height. Every converted icon already has #no-click, so none of them change. The light and dark mode toggles in rc/changelog/april-2025.md were a paragraph of their own, joined by , so the codemod treated the pair as inline icons and they dropped from 149x57 to about 63x24. They're now two standalone images separated by a blank line, back at their natural size. The had to go too: an image followed by isn't alone in its paragraph, so it would have stayed inline. As block images they stack rather than sit side by side. Merged main first, which brings in #4189's conversion of the tls-configuration-procedure.md screenshot the review asked about. Learned: an image that ends its line with isn't alone in its paragraph, so a blank line alone won't make it a block image Constraint: render-image.html adds img-inline only to inline, local, #no-click images; a screenshot sharing a paragraph with text must stay full size Ticket: DOC-7128 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Thanks for the review and the assessment. Changes are in 35736b7, on top of a merge from
Re-verified after the changes:
|
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 35736b7. Configure here.
| {{<image filename="images/rc/mode-select-dark.png#no-click" alt="Mode selection toggle with dark mode selected." class="inline" >}} | ||
|  | ||
|
|
||
|  |
There was a problem hiding this comment.
Changelog icons render as unsized blocks
Medium Severity
The light and dark mode toggles are now two standalone Markdown images separated by a blank line. With wrapStandAloneImageWithinParagraph off, each one is a block image, so the hook never adds img-inline and the td CSS fallback does not apply. They keep default prose image margins and native dimensions instead of scaling to the surrounding text, and they stack instead of sitting on one line.
Reviewed by Cursor Bugbot for commit 35736b7. Configure here.
There was a problem hiding this comment.
This is intentional, so I'm not changing it. These two images are mode-toggle screenshots (149×57), not UI icons. Converting them as a pair of inline icons was the regression: it shrank them to about 63×24, and the human review on this PR asked for exactly this fix, two standalone images at full size.
- No
img-inline, and thetdrule doesn't apply: correct and intended. Both are only for icons inside running text or table cells, and the hook now requires#no-clickon an inline image specifically so screenshots keep their size. - Prose margins and native dimensions: that's how every standalone screenshot on the site renders. On
mainthese two sat inside a paragraph, and that paragraph was padded by the same prose margins. - Stacking instead of side by side: a known trade-off of making them block images, called out in the review reply and the commit message. Keeping them side by side at full size would need a class or raw HTML, which this migration avoids.
Verified in a browser: both render at their natural 149×57.
Runs build/migrate_image_shortcodes.py --inline-icons over 54 files in the rs/7.22/, rs/7.8/, and rs/7.4/ snapshots, converting 70 #no-click icon shortcodes to inline Markdown images sized by the CSS rule from #4192. No #no-click icon shortcodes are left in these snapshots. Verified against a #4192 build under the production baseURL: all 70 render with the same src, no width, and class img-inline, with no other image changes. A scripted browser pass over all 54 affected pages found every icon at 1.5x its text size and every single-line block (64) at its normal line height. Ticket: DOC-7128 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Renders inline UI icons as Markdown images sized by CSS and converts 67 of them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2 participants
Note: I'm not sure if some of these icons render a bit too small or whether that even really matters. I'd appreciate any feedback anyone has to offer about this!
Summary
UI button icons (the
#no-clickimages inside sentences and table cells) were the last image shortcodes the codemod couldn't convert, because Goldmark has no inline attribute syntax to carry theirwidthandclass. This PR makes them plain inline Markdown images, sized to the surrounding text by one CSS rule:Part 1 of 2 for icons in DOC-7128. It adds the mechanism and converts 67 icons in 44 files across
rc/, unversionedrs/,rs/8.0/, andembeds/. Part 2 converts thers/7.22,7.8, and7.4snapshots and is stacked on this PR.How it works:
render-image.htmladds classimg-inlineto an image that's inside running text and points at a local/images/…file. External images, such as shields.io badges, are excluded.assets/css/index.cssgivesimg.img-inlinea height of1.5em, widthauto,vertical-align: middle, andmargin: -0.1em 0.IsBlockis true), so the hook can't mark it. Cells are matched in CSS bytd img[src*="#no-click"]instead.build/migrate_image_shortcodes.py --inline-iconsconverts only#no-clickimage shortcodes that aren't their own paragraph, and drops theirwidthandclass.info-icon.pngimages that lack#no-click, because inline sizing would shrink them.AGENTS.mdgains a sentence on writing icons.Visible changes, chosen in a browser trial:
main, the shortcode icons inherit proseimgmargins that pad every line or table row holding an icon to 85–104px. The new rule removes that, so icon steps line up with the steps around them. For example, theaccess-managementicon table shrinks from 429px to 197px tall.The rule deliberately isn't keyed on
#no-clickalone. 20 standalone screenshots carry#no-click(a REST API diagram among them), and they would shrink to text height.Verification
mainand this branch under the production baseURL (/docs/latest/): both succeeded (19,664 pages), and the hook reported no missing images.src,widthremoved, classimg-inline(or no class in a table cell), and alt text unchanged or losing only emphasis markers. That covers 62 icons on 42 pages, with 0 unexpected changes. No image without#no-clickgained the class anywhere on the site.#no-clickshortcodes left in the 44 files. In every changed file, the text with all images stripped is byte-identical before and after. The default mode's output is byte-identical tomain's script.create-db.md, andtls-configuration-procedure.md, which was already flagged as dead in DOC-7128 embeds-oss: convert embeds/ and oss_and_stack/ images #4189.🤖 Generated with Claude Code
Note
Low Risk
Docs-site presentation and migration tooling only; no runtime product, auth, or data-path changes. Risk is limited to possible icon sizing regressions on affected pages.
Overview
Inline UI icons (
#no-clickimages in sentences, steps, and table cells) move from{{< image >}}shortcodes to plain Markdown (), with CSS sizing them to 1.5em instead of per-shortcodewidth/class.Rendering:
render-image.htmladds classimg-inlinefor non-block local images whose URL contains#no-click.index.cssstylesimg.img-inlineandtd img[src*="#no-click"](table-cell icons are block-level in Goldmark). AGENTS.md documents the inline-icon pattern.Tooling:
migrate_image_shortcodes.pygains--inline-iconsto convert eligible#no-clickshortcodes and drop width/class; block-paragraph screenshots are skipped.Content: ~67 icons across 44 files in Redis Cloud (
rc/), Redis Software (rs/andrs/8.0/), and embeds—visible change is more consistent icon scale and tighter line/table row height where proseimgmargins had inflated rows.Reviewed by Cursor Bugbot for commit 35736b7. Bugbot is set up for automated code reviews on this repo. Configure here.