Skip to content

fix: keep tag/filter doc warnings on their own line on hover#1215

Merged
graygilmore merged 1 commit into
Shopify:mainfrom
ryandiginomad:fix/506-hover-warning-blockquote
May 29, 2026
Merged

fix: keep tag/filter doc warnings on their own line on hover#1215
graygilmore merged 1 commit into
Shopify:mainfrom
ryandiginomad:fix/506-hover-warning-blockquote

Conversation

@ryandiginomad
Copy link
Copy Markdown
Contributor

What are you adding in this PR?

Fixes #506.

When a Liquid tag/filter's documentation contains a warning (a > Caution: / > Note: blockquote in the source docs), the hover tooltip flattened it onto the previous line, so the warning ran into the surrounding text and was easy to miss (the image_url filter is the example in the issue).

The cause is in MarkdownRenderer.sanitize():

?.replace(/(^|\n+)>/g, ' ')   // replaces "newline(s) + escaped >" with a single space
.replace(/>/g, '>')

The docs HTML-escape > to >, so blockquote lines start with >. The first replace swallows the newline together with the > marker and substitutes a single space — collapsing a multi-line blockquote into the preceding paragraph.

The fix drops that lossy first replace. The existing >> conversion on the next line then preserves the admonition as a proper markdown blockquote, which both the VS Code hover renderer and CodeMirror render on their own lines.

It's a one-line removal (plus a regression test and a changeset).

Tophatting

Rendered hover markdown for the image_url filter, before and after (focused on the warning region):

Before — warning collapsed into the bullet list / prose:

- `country`  Caution: You need to specify either a `width` or `height` parameter. If neither are specified, then an error is returned.  Note: Regardless of the specified dimensions, an image can never be resized to be larger than its original dimensions.

After — warnings preserved as blockquotes on their own lines:

- `country`

> Caution:
> You need to specify either a `width` or `height` parameter. If neither are specified, then an error is returned.

> Note:
> Regardless of the specified dimensions, an image can never be resized to be larger than its original dimensions.
  • Added a regression test in MarkdownRenderer.spec.ts (built from the real image_url doc markup). Happy to add a VS Code hover screenshot too if you'd prefer that over the rendered-string comparison.

Before you deploy

  • I included a patch bump changeset

A note for reviewers

I render the warnings as markdown blockquotes (> …). I couldn't tell from the history why the original code stripped the > marker, so if you'd rather these warnings render as plain paragraphs instead of blockquotes, I'm happy to adjust — the key fix is just not collapsing them onto the previous line.


🤖 Disclosure: this change was investigated and drafted with AI assistance (Claude Code). I've reviewed the diff, understand the root cause, and verified it against the repo's test suite — the test plan and reasoning are mine to defend.

@ryandiginomad ryandiginomad force-pushed the fix/506-hover-warning-blockquote branch from fd4a93b to b393efb Compare May 28, 2026 06:59
@ryandiginomad
Copy link
Copy Markdown
Contributor Author

I have signed the CLA!

@ryandiginomad ryandiginomad marked this pull request as ready for review May 28, 2026 07:18
@ryandiginomad ryandiginomad requested a review from a team as a code owner May 28, 2026 07:18
Copy link
Copy Markdown
Contributor

@graygilmore graygilmore left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you Ryan! This has annoyed me for quite some time but I haven't got around to fixing it 😄

Would you mind rebasing with main? I've made a change to our CI workflow so that we can approve it to run in outside contributor PRs like yours.

Doc admonitions (e.g. the `image_url` filter's Caution/Note blockquotes)
were collapsed onto the previous line on hover. `sanitize()` replaced
"newline(s) + escaped >" with a single space, flattening multi-line
blockquotes into the surrounding text. Drop that lossy replace so the
existing `>` -> `>` conversion preserves them as markdown blockquotes,
which both the VS Code hover and CodeMirror render on their own lines.

Fixes Shopify#506
@ryandiginomad ryandiginomad force-pushed the fix/506-hover-warning-blockquote branch from b393efb to e7226d8 Compare May 29, 2026 02:52
@ryandiginomad
Copy link
Copy Markdown
Contributor Author

Thanks @graygilmore! Rebased onto the latest main — should be ready for the CI approval whenever you get a chance. Glad this one's finally getting fixed 😄

@graygilmore graygilmore merged commit b4fdc0c into Shopify:main May 29, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Description fails to render properly for some tags and filters on hover

2 participants