feat: clarify label & add help text with link by coderGtm · Pull Request #70451 · WordPress/gutenberg

coderGtm · 2025-06-17T08:00:24Z

What?

Closes #20208

This PR aims to add more clarity the Link Rel attribute in image URL input by:

Changing the label from 'Link Rel' to 'Link Relation'
Adding a help text with a link to external documentation for more information.

Why?

It was discussed in #20208 to clarify the label and add helper text to clarify what the "link rel" is actually for. It was also proposed to add a link to https://developer.mozilla.org/docs/Web/HTML/Attributes/rel so users can get more information easily.

How?

Changed label to 'Link Relation' for better understanding and readability.
Added a help text with a brief explanation to the attribute.
Used ExternalLink to link external documentation so users can get more info.

Testing Instructions

Open a post or page
Insert an image block or click on an existing image block
In the toolbar, click on Link icon.
Click the down arrow to open more settings
Check that the first field contains 'Link Relation' as label instead of 'Link Rel'
Check that a help text with correct external link is present below the input field.

Screen.Recording.2025-06-17.at.1.26.05.PM.mov

Screenshots

Before	After

github-actions · 2025-06-17T08:01:07Z

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @coderGtm! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

github-actions · 2025-06-17T08:29:38Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: coderGtm <gautam23@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: joedolson <joedolson@git.wordpress.org>
Co-authored-by: yyppsk <pranjalpratapsingh@git.wordpress.org>
Co-authored-by: karmatosed <karmatosed@git.wordpress.org>
Co-authored-by: skorasaurus <skorasaurus@git.wordpress.org>
Co-authored-by: Soean <soean@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

coderGtm · 2025-06-24T07:43:36Z

Hi @ellatrix

Did you get a chance to look into this PR? I have clarified the purpose and the text as discussed and agreed upon by @Soean, @karmatosed and @skorasaurus in #20208

Is there anything else that I need to do? I am fairly new to contributions here so not sure.

Thanks

yyppsk · 2025-07-02T14:47:23Z

Hi @coderGtm,

I’ve tested this PR on on block editor and have put my testing report below.

Machine: macOS Air (M3)
Browsers Tested: Chrome, Safari, Firefox
Environment: WordPress Block Editor (Gutenberg)

Summary

This report confirms that the proposed updates in PR work as intended. The changes enhance the clarity of the "Link Rel" attribute in the image block by updating the label and providing contextual help text with a link to relevant documentation.

Scope of Change

The label Link Rel has been changed to Link Relation.
A help text has been added below the input field to explain its purpose.
A link to MDN documentation on the rel attribute has been included for users seeking more information.

Steps to Reproduce

Open a post or page in the WordPress Block Editor.
Insert a new image block or select an existing image block.
Click the Link icon from the toolbar.
Click the dropdown arrow to reveal additional settings.
Observe the first field in the dropdown.

Expected Results

The input label should display as Link Relation.
A help text should appear below the field, briefly explaining the attribute.
The help text should include a functional hyperlink to external documentation (MDN).

Actual Results

Label: Displays as Link Relation correctly in all tested browsers.
Help Text: Visible below the input field and clearly explains the use of the attribute.
External Link: Redirects correctly to the MDN documentation and opens in a new tab.
Cross-Browser Rendering: Verified in Chrome, Safari, and Firefox. No rendering or interaction issues encountered.

Before and After Summary

Context	Value
Before	Label: `Link Rel`
	No help text
After	Label: `Link Relation`
	Help text with MDN link added

Before	After

karmatosed · 2025-07-22T19:52:44Z

@Mamaduka looping you in for a review here, to me this is ready to go so taking off the design review. I also approve first the code but I would like a second opinion just to be sure.

Mamaduka · 2025-07-23T04:42:27Z

I think this falls under the "Need Decision" label. I don't have a strong opinion; both labels work for me. Considering it's an advanced setting, users shouldn't just fill it out.

Additionally, the terminology needs to be consistent across the project. The image link control isn't the only place with this field. Examples:

I would hold off making further changes until there's a final decision.

joedolson · 2025-07-29T15:53:55Z

I think this is a sensible change. The label is pretty unclear as it is, and improving the clarity of that field is valuable.

It is true that relatively few people are likely to use it, but we might as well make it easier for those who do.

…berg into fix/link-rel-text

Mamaduka

@coderGtm, thanks for refreshing the branch. It appears that it now contains some unrelated changes.

Additionally, remaining feedback needs to be addressed, and this field needs to be made consistent across the editor.

Mamaduka · 2025-09-02T02:32:44Z

Changes to this file are unrelated to this PR.

Mamaduka · 2025-09-02T02:33:40Z

coderGtm · 2025-09-04T13:19:06Z

@Mamaduka I mistakenly merged another branch into this causing other PR's changes to be added here. I will remove them. Additionally, by remaining feedback do you mean applying this Link Rel changes everywhere in Gutenberg?

Mamaduka · 2025-09-06T05:42:16Z

Additionally, by remaining feedback do you mean applying this Link Rel changes everywhere in Gutenberg?

That's right. The similar "Link Rel" fields should be consistent across the app.

coderGtm · 2025-09-08T14:19:07Z

@Mamaduka I have made the changes across Gutenberg. Please take a look and let me know if anything else needs to be done. Thanks!

Mamaduka

Thanks, @coderGtm!

The code changes look good and test well. I've left some notes regarding text copy, based on project guidelines. But I would defer to @karmatosed and @joedolson regarding it.

Mamaduka · 2025-09-09T08:26:40Z

 				__next40pxDefaultSize
 				__nextHasNoMarginBottom
-				label={ __( 'Link rel' ) }
+				label={ __( 'Link Relation' ) }


Suggested change

label={ __( 'Link Relation' ) }

label={ __( 'Link relation' ) }

I think similar labels use sentence case. See: https://github.com/WordPress/gutenberg/blob/trunk/docs/contributors/documentation/copy-guide.md#five-pay-attention-to-capitalization

Mamaduka · 2025-09-09T08:28:20Z

+				help={
+					<>
+						{ __(
+							'The Link Relation attribute defines the relationship between a linked resource and the current document.'


Suggested change

'The Link Relation attribute defines the relationship between a linked resource and the current document.'

'The link relation attribute defines the relationship between a linked resource and the current document.'

I think we should use standard casing here. This matches casing in the MDN article.

Note: Label and text changes should be the same everywhere.

coderGtm · 2025-09-09T10:45:51Z

Thanks for pointing it out @Mamaduka and for taking the time to review and approve the PR. Reading the guidelines you linked, it seems the changes you suggested should be the way to go.

I can still wait for @karmatosed and @joedolson for their nod so we are on the same page.

joedolson

Only one change I'd like to see: to improve the link text for more information.

joedolson · 2025-09-09T16:15:40Z

+						help={
+							<>
+								{ __(
+									'The Link Relation attribute defines the relationship between a linked resource and the current document.'


I'd like to avoid using meaningless link text like "Learn more". Can we instead place the link on the word "link relation attribute"?

Thanks @joedolson. I'd incorporate those changes. Btw, what do you think about the sentence case thing suggested by @Mamaduka earlier?

@Mamaduka @joedolson I have got the link inline with element interpolation. From what I think, now it makes sense to keep the casings as it is since now "Link Relation" is a term that we refer externally directly by clicking on it. I am not sure though and not aware if any guidelines are there for such a case. What do you think?

Don't have a strong opinion here; I usually follow the text copy guidelines. We could keep casing in the help text, but let's fix it for the label.

Do you mean the label above the input box? That is capitalized automatically. All labels are like that.

See #70451 (comment).

Got it! Done.

joedolson · 2025-09-09T16:16:03Z

+									help={
+										<>
+											{ __(
+												'The Link Relation attribute defines the relationship between a linked resource and the current document.'


See previous request.

joedolson · 2025-09-09T16:16:15Z

+											help={
+												<>
+													{ __(
+														'The Link Relation attribute defines the relationship between a linked resource and the current document.'


See previous request.

joedolson · 2025-09-09T16:16:28Z

+					help={
+						<>
+							{ __(
+								'The Link Relation attribute defines the relationship between a linked resource and the current document.'


See previous request.

joedolson · 2025-09-09T16:16:38Z

+					help={
+						<>
+							{ __(
+								'The Link Relation attribute defines the relationship between a linked resource and the current document.'


See previous request.

…ements

Mamaduka · 2025-09-11T15:04:38Z

+						'The <linkRel>Link Relation</linkRel> attribute defines the relationship between a linked resource and the current document.'
+					),
+					{
+						linkRel: (


Suggested change

'The <linkRel>Link Relation</linkRel> attribute defines the relationship between a linked resource and the current document.'

),

{

linkRel: (

'The <a>Link Relation</a> attribute defines the relationship between a linked resource and the current document.'

),

{

a: (

Suggestion: We can just use `a as a link placeholder, it's a typical pattern in core, and translators might be more aware of it.

I have made these changes @Mamaduka
Thanks!

Mamaduka

Thanks for the follow-ups, @coderGtm!

The changes look good to me. @joedolson, what do you think?

joedolson

I'm a little on the fence about the initial capitalization, but I don't think it's important enough to hold this up.

t-hamano · 2025-09-16T07:14:04Z

Nit: Personally, I'd be happy if the links were translatable. MDN has many pages localized into several languages. Site users may not be comfortable with English and would prefer to view resources in their own language:

Example:

gutenberg/packages/block-library/src/cover/edit/inspector-controls.js

Lines 308 to 319 in 228c3b5

    
           <ExternalLink 
        
           	href={ 
        
           		// translators: Localized tutorial, if one exists. W3C Web Accessibility Initiative link has list of existing translations. 
        
           		__( 
        
           			'https://www.w3.org/WAI/tutorials/images/decision-tree/' 
        
           		) 
        
           	} 
        
           > 
        
           	{ __( 
        
           		'Describe the purpose of the image.' 
        
           	) } 
        
           </ExternalLink>

coderGtm added 2 commits June 10, 2025 13:06

feat: restore code

9a1a576

feat: clarify label & add help text with link

95ebc0d

github-actions Bot added the First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository label Jun 17, 2025

i18n: remove en-US preset from doc link

7a0e65c

coderGtm marked this pull request as ready for review June 17, 2025 08:29

coderGtm requested a review from ellatrix as a code owner June 17, 2025 08:29

t-hamano added [Type] Enhancement A suggestion for improvement. Needs Design Feedback Needs general design feedback. Needs Copy Review Needs review of user-facing copy (language, phrasing) labels Jun 17, 2025

coderGtm mentioned this pull request Jun 17, 2025

Change link relationship label. #20208

Closed

coderGtm added 2 commits June 20, 2025 12:52

Merge branch 'WordPress:trunk' into trunk

87d4657

Merge branch 'WordPress:trunk' into fix/link-rel-text

3c8418a

skorasaurus added [Focus] Accessibility (a11y) Changes that impact accessibility and need corresponding review (e.g. markup changes). Needs Accessibility Feedback Need input from accessibility labels Jun 25, 2025

karmatosed removed the Needs Design Feedback Needs general design feedback. label Jul 22, 2025

karmatosed requested a review from Mamaduka July 22, 2025 19:52

Mamaduka reviewed Jul 23, 2025

View reviewed changes

Comment thread packages/block-editor/src/components/url-popover/image-url-input-ui.js Outdated

coderGtm and others added 4 commits September 1, 2025 18:22

Merge remote-tracking branch 'upstream/trunk' into trunk

df5efda

Merge branch 'trunk' into fix/link-rel-text

0047bd8

Merge branch 'WordPress:trunk' into fix/link-rel-text

6288f0e

Merge branch 'fix/link-rel-text' of https://github.com/coderGtm/guten…

6d46aee

…berg into fix/link-rel-text

coderGtm requested review from ajitbohra and fabiankaegy as code owners September 1, 2025 13:05

fix: replace span with react fragment

9c17788

Mamaduka requested changes Sep 2, 2025

View reviewed changes

fix: remove unrelated changes

fcf900b

coderGtm added 3 commits September 8, 2025 16:22

Merge remote-tracking branch 'upstream/trunk' into fix/link-rel-text

31b697b

feat: update all 'Link rel' label to 'Link Relation' and add help text

2b71099

Merge remote-tracking branch 'upstream/trunk' into fix/link-rel-text

866c08d

Mamaduka approved these changes Sep 9, 2025

View reviewed changes

joedolson requested changes Sep 9, 2025

View reviewed changes

refactor: update help text for 'Link Relation' to use interpolated el…

a2bafbd

…ements

Mamaduka reviewed Sep 11, 2025

View reviewed changes

coderGtm added 2 commits September 15, 2025 14:01

fix: standardize label casing for 'Link Relation' to 'Link relation'

83ef20b

refactor: use 'a' as the link placeholder instead of 'linkRel'

2c610ef

Mamaduka approved these changes Sep 15, 2025

View reviewed changes

joedolson self-requested a review September 15, 2025 19:58

joedolson approved these changes Sep 15, 2025

View reviewed changes

Mamaduka merged commit 9f492ef into WordPress:trunk Sep 16, 2025
72 checks passed

github-actions Bot added this to the Gutenberg 21.7 milestone Sep 16, 2025

maxschmeling mentioned this pull request Oct 7, 2025

Add BlockCanvasCover SlotFill #72119

Closed

	label={ __( 'Link Relation' ) }
	label={ __( 'Link relation' ) }

	'The Link Relation attribute defines the relationship between a linked resource and the current document.'
	'The link relation attribute defines the relationship between a linked resource and the current document.'

Conversation

coderGtm commented Jun 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Screenshots

Uh oh!

github-actions Bot commented Jun 17, 2025

Uh oh!

github-actions Bot commented Jun 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderGtm commented Jun 24, 2025

Uh oh!

yyppsk commented Jul 2, 2025

Summary

Scope of Change

Steps to Reproduce

Expected Results

Actual Results

Before and After Summary

Uh oh!

karmatosed commented Jul 22, 2025

Uh oh!

Mamaduka commented Jul 23, 2025

Uh oh!

Uh oh!

joedolson commented Jul 29, 2025

Uh oh!

Mamaduka left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coderGtm commented Sep 4, 2025

Uh oh!

Mamaduka commented Sep 6, 2025

Uh oh!

coderGtm commented Sep 8, 2025

Uh oh!

Mamaduka left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coderGtm commented Sep 9, 2025

Uh oh!

joedolson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coderGtm commented Jun 17, 2025 •

edited

Loading

github-actions Bot commented Jun 17, 2025 •

edited

Loading