Block audit: Heading

[sarahmonster]

Note: We'll be doing these audits in waves and editing this as we work through the blocks, so this text will be updated and fleshed out as we progress. See the full picture here.

Overview

Name: Heading
Description: Insert a headline above your post or page content.
Category: Common blocks
CSS class: None on frontend, wp-block-heading in editor
Can be converted to: Quote, cover image, paragraph

States

Empty:

Blinking prompt

Selected:

Unselected:

Placeholder:

If you click through without adding any text, you'll see greyed-out text that says "Write heading...":

Primary (toolbar) settings

H2, H3, H4, bold, italic, strikethrough, link

Secondary (sidebar) settings

Heading settings: H1, H2, H3, H4, H5, H6
Text alignment: left, centre, right
Advanced: Additional CSS Class, HTML Anchor

Frontend appearance

Gutenberg starter theme:

Atomic Blocks

twentyseventeen:

twentyten:

Documentation

No devdocs in https://github.com/WordPress/gutenberg/tree/master/core-blocks/heading

Suggestion for user-facing docs:

Performance on mobile

Accessibility

Bugs/errors

Individual issues will be opened for these soon

• Bolding part of the heading has no effect on its appearance. (Bolding part of a heading has no visual indication #11107)
• Typing a hard return (Enter) in the middle of a heading, then using command-z to undo deletes everything that appeared after the line break. (Text is deleted when undoing a hard break inserted into a heading #11108)
• 3. Stray
  tags sometimes appear within a heading. (Firefox: RichText: invisible trailing <br> tags #5872)

Suggestions

Individual issues will be opened for these soon

• In the paragraph block, alignments are in the primary toolbar. Here, they're in the secondary toolbar. They should be consistent (I'd go with the primary toolbar.) (Unify the block toolbar for all text blocks #3785)
• This should probably be convertible to a subheading block, or (better), combined into a single heading block. (Related: Subhead should support multiple use #8140)
• Consider adding colour settings to more closely align with paragraph—I'd skip on the size though, since it sort of defeats the purpose. (Consider adding color and text size customizations to all text-based blocks.  #8171)
• Use /h1, /h2, /h3, etc in the slash inserter commands. (Improved shortcuts for inserting headings #7438)

[ZebulanStanphill]

In the paragraph block, alignments are in the primary toolbar. Here, they're in the secondary toolbar. They should be consistent (I'd go with the primary toolbar.)

I think the term everybody uses is "inspector" or "block inspector", rather than secondary toolbar.

Subheadings should remain separate from the Heading block, in my opinion. Just to be clear, a Subheading is something that should not use the <h1> to <h6> tags. They are commonly used as leads or little statements below the title of the article, though I think I have seen them used the headings of each section of an article, albeit rarely.

https://minecraft.net is the first example that comes to my mind as an example of posts using subheadings. Hover over the blog posts in the masonry layout and a subheading will appear below the title. The subheading is also shown below the title when you go to a blog post.

The HTML 5.2 specification shows some other uses of the Subheading block, including cases where you would have multiple subheadings following a single heading.

https://www.w3.org/TR/html52/common-idioms-without-dedicated-elements.html#common-idioms-without-dedicated-elements

Notably, I think the Subheading block, in the context of using it for short blurbs of text below the title (like on news sites), may not even belong in post_content, and should be placed in the same area as the title heading. Of course, Gutenberg can not yet edit that area (though it will be able to in the future).

That said, the Subheading block is still useful for situations where you have a subheading below each section heading in your post or page.

You might wonder why you could not just use a Paragraph block to accomplish the same thing. Well, you could. But the Subheading block is slightly more semantic, meaning that:

• Themes could provide special styles to the Subheading block, including multiple styles you could switch between, without exposing them to normal Paragraph block styles and vice-versa.
• If a <subheading> element was ever added to HTML, existing Subheading blocks could be retroactively updated to use the new element, providing increased semantics to existing websites.
• When Gutenberg gets the ability to edit stuff outside of post_content, there will already be a Subheading block that can be used there and would presumably already have a bit more theme/plugin support than it would if it were added later.

[kjellr]

In the paragraph block, alignments are in the primary toolbar. Here, they're in the secondary toolbar. They should be consistent (I'd go with the primary toolbar.)

Related: #3785

[sarahmonster]

All issues here have been filed as individual issues, so I'm going to go ahead and close out this tracking bug. Feel free to comment on if I missed anything, or open new issues as needed! 💪