Block audit: Subheading

[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: Subheading
Description: What’s a subhead? Smaller than a headline, bigger than basic text.
Category: Common blocks
CSS class: wp-block-subhead in frontend, wp-block-subhead in editor
Can be converted to: Paragraph

States

Empty:

Selected:

Unselected:

Placeholder:

Primary (toolbar) settings

Align left | right | centre, bold, italic, strikethrough, link

Secondary (sidebar) settings

Advanced: Additional CSS Class

Frontend appearance

Gutenberg starter theme:

Atomic Blocks

twentyseventeen:

twentyten:

Bugs/errors

Individual issues will be opened for these soon

• Typing a hard return (Enter) in the middle of a heading creates two headings, which is inconsistent with how a heading works.

• Italicising text has no effect. This should un-italicise, or perhaps the italics should be turned on my default.

• Text lacks sufficient contrast. (Subheading block: text lacks sufficient contrast #8716)

Suggestions

Individual issues will be opened for these soon

• Kill it with 🔥. As a new user, I don't have any sense of why there are two different blocks for what are, in many respects, basically the same thing. My understanding, having read various issues, is that the subheading is visually heading-like, but semantically not-heading like, which can be useful for SEO stuff and also for newsrooms or anyone generating a table of Contents from h1-6 headings. That's a good advanced feature if you understand what's behind it, but as a new/inexperienced user, it's totally confusing. A better approach might be to provide this as an advanced setting on the heading block. (Related: Subhead should support multiple use #8140)

• Should be convertible to (at very least) a heading.

• Alignment settings should be consistent with the heading block. (See Block audit: Heading #8230)

• 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)

• Allow for as many subheads per page as people want. (See also https://github.com/TomodomoCo/tomodomo-gutenberg-infinite-subheads)

• The placeholder text looks almost exactly the same as the non-placeholder styling, making it confusing.

• The icon is the exact same as the one used for preformatted text—and it looks like a paragraph, rather than a heading.

[chrisvanpatten]

Just for some extra context, a subhead is in no way a heading. The name is very misleading, but newsrooms have used the term for decades (and will continue to use it) so we're stuck with it :)

(It's also called a "dek" or "deck", "standfirst" in the UK, "kicker", and occasionally "subhed" sans-A.)

I don't know that I'm totally on board with ditching it, although admittedly I'm biased because my clients are editorial teams, newsrooms, and publishers. That said, if it were removed, I'd add it back as a block style option on the Paragraph block, which honestly might be more intuitive anyway.

[ZebulanStanphill]

Copy-pasting what I posted in #8230 (which probably should have been posted here in the first place 😛):

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.

[sarahmonster]

Thanks for the extra context here! It sounds like there are two potential use cases here:

1. A journalistic subhead
2. A subtitle for the post itself (referred to in the HTML spec linked above)

I'm not entirely sure which this one is intending to act as, which may be part of the problem. The fact that it's limited to a single instance leads me to think it may be intended as a subtitle, but that doesn't seem to track with its description. ("What’s a subhead? Smaller than a headline, bigger than basic text.")

If it's intended to act as a subtitle for the post itself, I'm not certain that really belongs inside post content at all, especially if people want to use it on archive pages and the like (which is a pretty common use case). With the current implementation of WordPress, people tend to accomplish this by either using the post excerpt, or by installing one of the many subtitle plugins. If you wanted to accomplish the Minecraft example using Gutenberg, for instance, you couldn't.

For the subhead, I still feel it might be better if the block were incorporated into either the heading or the paragraph blocks. From the description here,

A subhead (also sub-headline, subheading, subtitle or deck; subhed or dek in journalism jargon) can be either a subordinate title under the main headline, or the heading of a subsection of the article.[8][full citation needed] It is a heading that precedes the main text, or a group of paragraphs of the main text. It helps encapsulate the entire piece, or informs the reader of the topic of part of it. Long or complex articles often have more than one subhead. Subheads are thus one type of entry point that help readers make choices, such as where to begin (or continue) reading.

So again, we have two potential meanings here: the subtitle, and the subheading. From this, though, it rather sounds like this is less of a "heading" and more of a full paragraph, stylistically, and that usage between different publications could very substantially. @chrisvanpatten I'd love if you could share some examples of subheads in use—I think this might really help clarify how newsrooms are using this feature so that we can sort out a balance between providing utility for power-users, and not confusing beginners.

If we wanted to retain this as a standalone block, I'd recommend at least the following:

1. Rename it to "subhead" so it's a bit more distinct from "heading", especially since "subhead" seems to be more standard than "subheading".
2. Move it out of common blocks. A section (or add-on plugin pack) for "blocks for journalism and newsrooms" could be more appropriate, and would reduce the chance of user confusion ("Do I use a heading, or a subheading?") here.
3. Make it repeatable—the limitation doesn't seem to respect the full range of use cases here.
4. Improve the description so it's clear what it's intended to be used for.

[chrisvanpatten]

A few quick examples:

Guardian:

NiemanLab:

Pew Research:

All are rendered via <p> tags, fwiw. Also, interestingly, Guardian's code calls it a "standfirst", Nieman's calls it a "deck", and Pew called it a "subhead". Just goes to show how everyone has their own preference on this :)

[sarahmonster]

Interesting—so it looks like here, the subtitle use case is actually the most prevalent—and it looks as though some of them could be part of the post body, but others (Nieman Lab) aren't.

Looking at the semantic structure of the other two sources, it looks as though the subhead/whatever-it-is-anyway isn't part of the post body in any of the cases... it's typically a top-level element that's separate from the post body entirely (or at the same level as the post body, the title, the meta), like here:

Both Pew Research and Neiman Lab also uses the subheads on archive pages, which wouldn't be possible with the current implementation of subheads in Gutenberg, unless I'm mistaken. (But would be possible with a subhead plugin or the post excerpt.)

Interestingly, all these options do use a <p> tag, only Neiman Lab actually uses a proper "paragraph" if we define "paragraph" as "at least a sentence with a full stop".

It seems like, given these use cases, the subhead really makes more sense as part of the post meta, rather than part of the post content itself—unless this block is intended as more of a layout block to be used in the future.

[ghost]

It seems like, given these use cases, the subhead really makes more sense as part of the post meta, rather than part of the post content itself

Definitely.

See also #4472 .

You may also want to see this in things like recent post widget or next/previous post navigation.

[kjellr]

Looking at the semantic structure of the other two sources, it looks as though the subhead/whatever-it-is-anyway isn't part of the post body in any of the cases... it's typically a top-level element that's separate from the post body entirely (or at the same level as the post body, the title, the meta)

Yep, that's how we do it over at Longreads too. Our dek/subhead is entered as the custom Excerpt for the post. That way, it's part of the post meta (rather than in the content), and can be reused as the post excerpt in social media descriptions, post archives, and other feeds.

[chrisvanpatten]

@kjellr We do the same thing; I expect that’s a common pattern.

Would be awesome if subheads and excerpts were somehow bridged together but I expect that’s a Phase 2 change.

[jurecuhalev]

It would be also great to have an option for this block as required and present by default field. Right now we use ACF to position it under Title so authors don't miss it.

[swissspidy]

Related: https://github.com/benhuson/wp-subtitle/, specifically https://github.com/benhuson/wp-subtitle/tree/gutenberg/develop

[sarahmonster]

@gandalfar when you say you're using ACF to position the block under the title, could you perhaps elaborate with a screenshot? I'm curious about real-life examples of this block in use. 🙂

[jurecuhalev]

At Val 202 (Slovenian National Radio Broadcaster), we'll have an article such as:
https://val202.rtvslo.si/2018/07/diskgolf/

In backend, this would look like:

The second line (Podnaslov prispevka would translate to Article subhead and an instruction that it can be max 200 characters). The input field is limited to 200 characters and it won't allow any more text after that. This is editorial decision that partially comes from the idea that it to forces journalists to not just paste first paragraph of text in there, but to think about what should go in there.

Because we have many external contributors that might login into Wordpress maybe once a month or even less, having a field visually be present automatically, at the correct reading flow, makes it a good visual cue to not forget to fill it in.

[sarahmonster]

Thanks for the additional context!

It looks like you're using a custom field here, rather than the subheading block that ships with Gutenberg, but it's definitely helpful to get a sense of the patterns in use here. Cheers!

[ZebulanStanphill]

I think the Subheading block still has potential use within the block content, but only if it is allowed to be used more than once, which is currently not the case.

If the Subheading block is only intended to be used for a subheading of the entire article, then I think the block may be promoting bad practice, since a post subheading belongs in the same area as the post title, not the post content. Gutenberg can currently only edit post_content, so the Subheading block does not make sense in that context.

While considerably less common, it is possible to have a subheading for a section in a document, and this is the only valid use-case I see for the Subheading block right now, which it ironically can not be used for due to its current one-per-post restriction.

Notably, the only way to semantically link headings and subheadings to a section is to group the heading and subheading together like so:

<section>
	<header>
		<h1>Heading</h1>
		<p>Subheading</p>
	</header>
	<p>The rest of the content of the section.</p>
</section>

(Yes, it is completely valid to use <h1> tags for a section heading if you use the <section> element. The heading is relative to the section and both Firefox and Chrome/Chromium style <h1>s to look smaller depending on how many <section>s they are nested in.)

Of course, you can only use the <header> element to mark up section headers if you use <section> elements to mark up your sections, rather than create implicit sections using the <h2>-<h6> elements.

I think a Container block that lets you change the HTML element it uses would be the ideal solution here. You could use Container blocks for both the <section>s and the <header>s.

But as things currently are, the Subheading block is actually pretty useless due to current Gutenberg limitations and unimplemented features. Even the cases where it is meant to be used are actually cases where it should not be used. The block actually encourages bad practice by implying that it should be used at the start of a post when it probably belongs outside of post_content.

I think the Subheading block should be removed and a Subheading-ish style variation should be added to the Paragraph block for future use or use in a plugin that adds a Container block that can be used for <section>s and <header>s.

If for some reason the Subheading block is not removed, then you should be able to use more than one in a post, but I do not really see the point since the markup I showed above provides actual semantics. <p>s in a <header> are semantically part of the heading of an article/section, while the current Subheading block has no real semantic meaning in HTML.

See also:
https://www.w3.org/TR/html52/common-idioms-without-dedicated-elements.html#subheadings-subtitles-alternative-titles-and-taglines

[Retrofitterdk]

After working quite a lot of years in journalistic newsrooms, I would conclude that the subheading block – in it’s current implemention – is pretty useless in a newsroom setting.

As already said here #6072, here #6409 and here a subheading block is not useful in newsrooms unless it can be queried separately in order to use in archive views/frontpages.

[youknowriad]

Subheading block is deprecated.

[strarsis]

@youknowriad: With what block has it been replaced?
I got many titles, each with a small descriptive text below.
Using title + paragraph as separate blocks would decouple it too much.
Should the theme/site plugin add its own title + subtitle/-heading block?

[rodrigoslayertech]

How to add a required subhead in my Gutenberg editor? For Custom Post Type?

[swissspidy]

@slowaways Please don't comment on old closed issues, instead raise your question on the core-editor Slack channel or in a new issue here on GitHub.