Skip to content

remove outdated hgroup content #18530

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 19, 2022
Merged

remove outdated hgroup content #18530

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 11 additions & 45 deletions files/en-us/web/html/element/hgroup/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,7 @@ browser-compat: html.elements.hgroup

{{HTMLRef}}

> **Warning:** `<hgroup>` should not be used because no assistive technology supports it, and as a result it has a detrimental effect on assistance for headings placed within it.
>
> For more information see the [Usage notes below](#usage_notes).

The **`<hgroup>`** [HTML](/en-US/docs/Web/HTML) element represents a multi-level heading for a section of a document. It groups a set of [`<h1>–<h6>`](/en-US/docs/Web/HTML/Element/Heading_Elements) elements.
The **`<hgroup>`** [HTML](/en-US/docs/Web/HTML) element represents a heading and related content. It groups a single [`<h1>–<h6>`](/en-US/docs/Web/HTML/Element/Heading_Elements) element with one or more [`<p>`](/en-US/docs/Web/HTML/Element/p).

{{EmbedInteractiveExample("pages/tabbed/hgroup.html", "tabbed-standard")}}

Expand All @@ -39,9 +35,11 @@ The **`<hgroup>`** [HTML](/en-US/docs/Web/HTML) element represents a multi-level
<tr>
<th scope="row">Permitted content</th>
<td>
One or more {{HTMLElement("h1")}}, {{HTMLElement("h2")}},
Zero or more {{HTMLElement("p")}} elements, followed by one
{{HTMLElement("h1")}}, {{HTMLElement("h2")}},
{{HTMLElement("h3")}}, {{HTMLElement("h4")}},
{{HTMLElement("h5")}}, and/or {{HTMLElement("h6")}}.
{{HTMLElement("h5")}}, or {{HTMLElement("h6")}} element,
followed by zero or more {{HTMLElement("p")}} elements.
</td>
</tr>
<tr>
Expand Down Expand Up @@ -82,30 +80,19 @@ This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_a

## Usage notes

> **Note:** The `<hgroup>` element has been removed from the HTML5 (W3C) specification, but it still is in the WHATWG version of HTML. It is partially implemented in most browsers, though, so is unlikely to go away.
> However, given that a key purpose of the `<hgroup>` element is to affect how headings are displayed by [the outline algorithm defined in the HTML specification](/en-US/docs/Web/HTML/Element/Heading_Elements#the_html5_outline_algorithm)—but **the HTML outline algorithm is not implemented in any browsers**—then the `<hgroup>` semantics are in practice only theoretical.
> So the HTML5 (W3C) specification provides advice on how to mark up [Subheadings, subtitles, alternative titles and taglines](https://html.spec.whatwg.org/multipage/semantics-other.html#common-idioms-without-dedicated-elements) without using `<hgroup>`.

The `<hgroup>` element allows the primary heading for a document section to be grouped with any secondary headings—such as subheadings or alternative titles—to form a _multi-level_ heading.

In other words, the `<hgroup>` element prevents any of its secondary [`<h1>–<h6>`](/en-US/docs/Web/HTML/Element/Heading_Elements) children from creating separate sections of their own in the outline—as those [`<h1>–<h6>`](/en-US/docs/Web/HTML/Element/Heading_Elements) elements otherwise normally would if they were not children of any `<hgroup>`.

So in the abstract outline produced by the [HTML outline algorithm defined in the HTML specification](/en-US/docs/Web/HTML/Element/Heading_Elements#the_html5_outline_algorithm), the `<hgroup>` as a whole forms a single logical heading, with the entire set of [`<h1>–<h6>`](/en-US/docs/Web/HTML/Element/Heading_Elements) children of the `<hgroup>` going into the outline as one _multi-level_ unit, to comprise that single logical heading in the abstract outline.

To produce any (non-abstract) _rendered_ view of such an outline, some choice must be made in the design of the rendering tool about how to render `<hgroup>` headings in such a way as to convey their multi-level nature. There are a variety of ways an `<hgroup>` might be shown in a rendered outline; for example:
The `<hgroup>` element allows the grouping of a heading with any secondary content, such as subheadings, an alternative title, or tagline. Each of these types of content represented as a `<p>` element within the `<hgroup>`.

- an `<hgroup>` might be shown in a rendered outline in with a colon character and space (": ") or other such punctuation after the primary heading and before the first secondary heading (and with the same or similar punctuation before any other secondary headings
- an `<hgroup>` might be shown in a rendered outline in with the primary heading followed by parentheses around the secondary heading(s)
The `<hgroup>` itself has no impact on the document outline of a web page. Rather, the single allowed heading within the `<hgroup>` contributes to the document outline.

Consider the following HTML document:
## Examples

```html
<!DOCTYPE html>
<title>HTML Standard</title>
<body>
<hgroup id="document-title">
<h1>HTML</h1>
<h2>Living Standard — Last Updated 12 August 2016</h2>
<h1>HTML: Living Standard</h1>
<p>Last Updated 12 July 2022</p>
</hgroup>
<p>Some intro to the document.</p>
<h2>Table of contents</h2>
Expand All @@ -115,30 +102,9 @@ Consider the following HTML document:
</body>
```

A rendered outline for that document might look like the following:

![](outline-colon.png)

That is, the rendered outline might show the primary title, _HTML_, followed by a colon and space, followed by the secondary title, _Living Standard — Last Updated 12 August 2016_.

Or, the rendered outline for that document might instead look like the following:

![Rendered outline that includes an \<hgroup> element, with parens around the secondary heading](outline-paren.png)

That is, the rendered outline might show the primary title, _HTML_, followed by the secondary title shown in parentheses: _(Living Standard — Last Updated 12 August 2016)_.

## Examples

```html
<hgroup id="document-title">
<h1>HTML</h1>
<h2>Living Standard — Last Updated 12 August 2016</h2>
</hgroup>
```

## Accessibility concerns

The presence of `hgroup` may remove information reported to assistive technology about the subheading portion of the heading group.
The `<hgroup>` presently has no strong accessibility semantics. The content of the element (a heading and optional paragraphs) is what is exposed by browser accessibility APIs.

## Specifications

Expand Down