Content block: Add indent controls

[carolinan]

What?

Closes #76536

Add block support for text indent to the content block.
Note that the PR previously added support to the excerpt block. This has been removed.

In block.json, the text indent is added to a selector that targets the first paragraph inside the block.

Testing Instructions

1. Activate a block theme. Make sure the theme's blog uses the post content block.
2. Go to Appearance > Editor > Styles > Blocks and select the content block.
3. In the block's typography setting, locate the option "Line indent" and enter a value. Save.
4. View the blog in the editor and the front, all post content blocks should show the first paragraph as indented.
5. Open a single post or page in the block editor. Confirm that the first paragraph of the content is indented (This is because of the setting on the content block, not the paragraph block).

Note that there are a few blocks that may look like they could be paragraphs, but are not indented, such as the login/out block. This block only uses the <a> tag.

[github-actions]

Flaky tests detected in cb53932.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/25787145217
📝 Reported issues:

• [Flaky Test] should disable Save draft button during a multi-file gallery upload #77701 in /test/e2e/specs/editor/various/upload-save-lock.spec.js
• [Flaky Test] should move focus back to the Publish panel toggle button when canceling #77721 in /test/e2e/specs/editor/various/publish-panel.spec.js

[github-actions]

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: carolinan <poena@git.wordpress.org>
Co-authored-by: juanfra <juanfra@git.wordpress.org>
Co-authored-by: henriqueiamarino <iamarinoh@git.wordpress.org>
Co-authored-by: juanmaguitar <juanmaguitar@git.wordpress.org>

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

[henriqueiamarino]

Thanks for the ping @carolinan. With images, I can think much clearer 😀

The example just illustrates my latest comment on the #76952 discussion. The feature should be removed from Paragraph because it affects too many elements on a site and causes weird situations like the one mentioned.

Users would have much more control if the feature were allowed in limited contexts, such as Content and Excerpt blocks.

[carolinan]

The excerpt block is just one paragraph, but the content can contain almost anything.

So should the indent on the content be applied to any text block?
Or only to a paragraph, if that is the first block?

[henriqueiamarino]

Content

Indent all

Yes, it should apply to all blocks once the user activates the feature in Global Styles > Content.

Indent first only

And it would be even better with an additional toggle to improve the experience from an editorial perspective. Users could choose to limit the indent to the first paragraph only.

Excerpt

As this is already limited, things would work well without extra effort.

[juanfra]

Thanks for working on this! I tested it locally and ran into some things. This is the first time I use this feature so that could be the reason. I have some questions/comments.

1. As we rely on the block paragraph classes (I'm stoked to finally see w have the CSS class in the paragraph block 😄), setting "Indent all paragraphs" on core/paragraph adds a .wp-block-paragraph { text-indent: ... } that bleeds into the other two (post-content and post-excerpt) regardless of their own settings. I think, for clarity, we need to explicitly decide which setting wins and enforce it in the selector logic. I think in the end there can be combinations that will bleed into each other or depend on which one is printing the CSS last, and we need to account for this (or document it).

2. The > direct-child selector is assuming that paragraphs are direct children of the post content wrapper. In many cases that will be true, but some templates may nest the content in groups/columns/etc. For those cases, I believe the feature will look broken.

Side notes, and unrelated to these changes:

A. The help text under "Indent all paragraphs" changes based on the toggle's own state, which makes things really confusing. Help texts should not change on action, they should be permanent. I think the controls for this feature could be more intuitive.

B. On a similar note, the + selector seems to be following the editorial convention of not indenting a paragraph that opens a new section (after a heading, image, etc.) and then indenting the rest. My first impression, after adding a value to "line indent" was that the feature wasn't working correctly, because it was indenting some paragraphs but not others. Again, I wasn't familiar with this. I think it can happen to others. We can maybe improve the way this is communicated so that people can understand that it is working as designed, and it's not a bug. I also think what I described in point A is not helping with this.

[carolinan]

@juanfra
I don't follow, about nr 1, the options are all disabled by default.
A default shouldn't override a setting that the user has activated.
So if the user enables indented paragraphs, it should affect the paragraphs, even if the user has not changed the content block settings. What am I missing?

[juanfra]

@carolinan sorry if I wasn't clear. I'm not saying a default should override a setting the user turned on. If indent is enabled globally, it should affect paragraphs everywhere, including post content. Agreed.

My point is what happens when the two settings differ. Paragraphs inside post content are also .wp-block-paragraph, so, if we have:

• Paragraph block .wp-block-paragraph { text-indent: X }
• Post content block .wp-block-post-content > .wp-block-paragraph { text-indent: Y }

Both hit the same paragraphs, and which wins comes down to CSS specificity, not an actual decision. It's also that if the values are different, with the > some paragraphs will have one indent, and some others (maybe inside groups or nested somewhere) will have another value. So my concern is that for these cases it can look difficult to understand. And maybe we have the opportunity to define which one wins when they differ, and document it.

Excerpt is a different story because, from what I understand, is always one paragraph. What I don't understand then is why the indent works different between excerpt and paragraph/post-content. For the latter, by default, it's indenting all paragraphs but the first. For excerpt it indents the first (and only).

A and B were just notes after experimenting with this feature and trying to understand. Probably discussions to have somewhere else.

[carolinan]

The settings will only differ when one of them is the default and the other is enabled so I still didn't understand.
Feel free to make any changes if you have time!

The excerpt block uses two paraphs when the "continue reading" / read more text is added by the user.

[juanfra]

Thanks Carolina!

The settings will only differ when one of them is the default and the other is enabled so I still didn't understand.

I believe there are other scenarios. Could be that one has 65px and the other one 45px. Could be that one has the "Indent all" and the other not.

The excerpt block uses two paraphs when the "continue reading" / read more text is added by the user.

True. What I meant is that for the excerpt there's only one paragraph with "content".

Unless I am missing something, I believe by default: For the other two blocks, the indent is applied not to the first paragraph of a section, but the others ( p + p, please check screencast). So the feature would be different for the paragraph/post-content and the excerpt blocks.

indent-works-on-subsequent-paragraphs-by-default.mp4

[carolinan]

I don't understand. The screencast is of a single paragraph in a post content block, and the setting that is changed is on the single paragraph. It has nothing to do with sections, since it is the single individual block that the setting is being changed on.

I am not saying "no", I am saying I don't understand. I don't think I can continue working on it if I can't understand what the settings are expected to do. That is also why I kept asking all those questions earlier (also on Slack).

[carolinan]

Are you expecting the words "This is the first..." to be indented when "all paragraphs" is toggled on?
That's not... I'm not a book editor but that is not a separate paragraph. Its a separate sentence, not a paragraph...? It is still part of the same paragraph block.

[juanfra]

Thanks for the follow-up @carolinan. I'm new to this feature as well.

What I am trying to show with the screencast: The indent setting for the paragraph block has an effect from the 2nd paragraph onwards.

With that screencast, I expose the inconsistency that I am referring to. The behavior of the same setting will be different on the excerpt block (where it indents the first and only paragraph) vs. paragraph/post-content (where it indents from the second paragraph onwards).

To summarize everything I shared in my messages:

• The indent setting for core/post-content and core/paragraph is applied to the same selectors. If the settings are different on those two (for example 10px on one and 30px on the other), there's no documentation or clarity on which one is going to be "winning".
• The indent setting for core/post-excerpt has different behavior (indents the one only paragraph) from the other two (indents by default the 2nd paragraph onwards).
• core/post-excerpt has have a setting to "Indent all paragraphs" when we know that there's only one paragraph.

I hope this helps clarify. I'm sorry the screencast confused you.

[carolinan]

I don't know how to solve the merge conflict nor update the branch with the changes from trunk after the documentation changes, there are too many errors.

[juanmaguitar]

Hi @carolinan 👋

About the conflict with docs/reference-guides/core-blocks.md

This PR was opened before #77612 was merged (Jun 7), which restructured the generated block docs: docs/reference-guides/core-blocks.md was removed in favor of an overview index at docs/reference-guides/core-blocks/README.md plus a per-block README.md (packages/block-library/src/<block>/README.md). Your branch still edits the now-deleted core-blocks.md, hence the conflict.

Resolution (tested locally, clean):

1. Merge the latest trunk into your branch.
2. On the conflict, drop the changes to core-blocks.md (accept its deletion).
3. Regenerate:

   npm run docs:build

4. Commit the regenerated files (the per-block README.md plus docs/reference-guides/core-blocks/README.md).

The textIndent entries regenerate automatically from the block.json change already in this PR, so nothing is lost.

Please, let me know if you're having more issues.

[carolinan]

@juanmaguitar Thank you.

@juanfra Because the settings is part of the typography panel, I have not found a way to address the Indent all paragraphs option on the excerpt block without adding an explicit check for that specific block, and then not print the control.
"hard coding" the block name (slug), which does not feel like the right solution to me. Nor is an "allowed list" the right solution.

[carolinan]

I'm more and more uncertain that we should implement this.
I guess I don't see why we can't use padding or margin for the excerpt block.

[henriqueiamarino]

I feel the same about it, @carolinan. I can’t think of a case in which Indent all would be used. I’d certainly use margin/padding to reach that result.

[henriqueiamarino]

Hi @carolinan, @juanmaguitar, and @juanfra, I finally understand what is going on with this one.

The option Indent All isn’t suitable for Excerpts since these blocks contain only a single paragraph, and 'indent all' would imply indenting every line—which can be more effectively managed with margins and padding. The same applies to the Paragraph block, where the feature is active today.

However, when discussing the Content block, it makes sense to consider. Indenting everything would involve indenting entire paragraphs, not individual lines. We are left with two choices: either indent the first line or indent all lines, as depicted in the image.

[carolinan]

But that is the opposite of how the setting works now for the paragraph block.
When Indent all paragraphs is off, it indents all but the first.
When Indent all is on, it indents all including the first.

(Which is very awkward because when it is on, it also indents the likes of "Sorry there are no search results")

[henriqueiamarino]

Yes, @carolinan, you’re right. Applying this to the Paragraph block causes many issues, including the one you reported (“Sorry, there are no search results”). For this reason, my first requirement was to remove the feature entirely from the Paragraph block and later have it fixed and applied to limited-use blocks, such as Excerpt and Content blocks.

[carolinan]

The problem is that is is not experimental: how do we remove something from the editor that users are already using? With as little impact as possible? Who makes the decision?

[henriqueiamarino]

I really don’t know about that. Internally, I am constantly asked to help improve the product and make the Editor better for everyone. That is my argument for suggesting fixes, especially ones like this that can indent oddly when paragraph lines are active on a site. I thought this was something we could and should fix. If not, that’s fine; I can take a step back. But then I may start to question all the work done here on GitHub to fix and evolve the product. I am not sure whether there is ever one person making the final call...

[carolinan]

I am not arguing or asking anyone to step back.
I am literally asking how do we remove an existing feature with as little impact as possible. In a product that is expected to always be backwards compatible. We normally don't make that kind of breaking change.

[henriqueiamarino]

No worries, I got you. I was just honest, as I don't know how to proceed after your question of who makes the call to change something that's already in use. 😅
My way of thinking was straightforward about the problem: if this is not the best solution and we can fix it, we do, period.
Once there's a community to consider before every action I don't know what to do...

[henriqueiamarino]

Although I believe few people would use it, given the issues it causes on the site.