Document Outline: Add check for the main element #68661
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
carolinan
added
[Feature] Document Outline
This comment was marked as resolved.
This comment was marked as resolved.
|
Size Change: +363 B (+0.02%) Total Size: 1.84 MB
ℹ️ View Unchanged
|
Mamaduka
reviewed
Jan 14, 2025
There was a problem hiding this comment.
I like this approach.
I think this is an improvement but now that the main is showing, I would expect the outline to display the main element and headings in relation to each other.
This makes sense. The new outline will consist of headings and main element(s). I think this means that there will be a single computeDocumentOutline method that can handle both elements.
The main element warnings still only make sense for the template post type.
|
Flaky tests detected in 2083cb2. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/12802173548
|
carolinan
commented
Jan 16, 2025
carolinan
added
the
[Focus] Accessibility (a11y)
…outline Add a new constant named isValid that is true or false depending on if there is one main element. Use isValid as a condition for displaying the warning text for the main element in the outline.
Combine the element count with the "headings by level" count. Remove duplicate li elements
|
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 If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
|
Thank you, @carolinan! I'll try to have a proper look at this next week. Question: Is updated headling nesting connected to the Maybe we should keep the simple version of the outline and just list the elements in the order they appear in the document. |
The visual change is only that the ul that wraps the children have some top and left margin. The em dash that shows before the heading level is not part of this update, it looks like that on trunk as well. |
|
Or maybe you are not thinking of the visual, but suggesting that I should flatten the list of blocks? I tried it early on, and when I ran into issues I may - have gotten carried away and made the code too complex. |
Exactly. Sorry if I wasn't clear. |
Also: Add a TODO for the missing title, with a link to the open issue. Remove unused CSS Add parentheses around the warning message for the main, to match the headings.
|
I have flattened the inner blocks and simplified the counting of the elements and the render. I kept two conditions that each add a |
|
It is assumed that the best practice is that the But there is nothing preventing changing the HTML tag to a Are there scenarios when the main needs to be added to the post content? Perhaps if the user does not have permission to edit templates? In classic themes, there will not be a way to confirm if the templates have a main, it could only warn for duplicate mains in the post content... |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What?
This PR description was updated 2025-01-17.
This PR updates the DocumentOutline component to include a check for blocks with the
maintagName attribute.The outline displays headings and blocks with the main element, including nested blocks.
If there is more than one main, there is a warning with the text:
"Your template should have exactly one main element. Adjust the HTML element in the Advanced panel of the block."
If the main is missing, the warning says:
"The main element is missing. Select the block that contains your most important content and add the main HTML element in the Advanced panel."
(The warning for incorrect heading levels remains the same.)
Alternative to #68656
Closes #35354
Why?
Having a single
<main>element in a template is important for accessibility, but also for the Zoom Out feature.The skip link feature is only enabled on templates that has a
<main>element.See the issue for more details.
Testing Instructions
Activate a block theme
Go to Appearance > Editor and open any template.
Open the List View
Open the Document Outline tab.
Locate or add a block that has the
<main>HTML element: This is usually a group, but any block with thetagNameattribute could be using it.To add the main HTML element using the interface option, select a container block, open the Block Settings Sidebar, and open the Advanced panel. Select the main in the HTML element option.
Confirm that the main element is showing in the Document Outline.
Confirm that selecting the item in the Outline selects the block.
Duplicate the block that has the
<main>element and confirm if both main elements are listed in the Outline.Move one of the mains inside the other. Add a few heading blocks. Confirm that both the nested main and the nested heading blocks show in the outline.
Delete all blocks with a
<main>element and confirm if there is a text at the top of the Outline that explains that the template should have one main.Test that there are no regressions in the post editor. The post editor should not show warnings for a missing main element.
Test that there are no regressions in the post editor when choosing the option "Edit template.". When the template is edited, the post editor should show warnings for a missing main element.
Activate a classic theme.
Test that there are no regressions in the post editor. The post editor should not show warnings for a missing main element.
Screenshots or screencast
Before:
No warnings:
All the following screenshot are from the Site Editor, with the PR:
No warnings:
Neither main or headings:
A heading, but no main:
Multiple main elements and incorrect heading order, with mains nested in mains:
I added 8px margin to the
<ul>that is used to wrap the nested items.