Skip to content
This repository has been archived by the owner. It is now read-only.

Add <h> element #774

Closed
jonathantneal opened this issue Jan 17, 2017 · 213 comments
Closed

Add <h> element #774

jonathantneal opened this issue Jan 17, 2017 · 213 comments

Comments

@jonathantneal
Copy link

@jonathantneal jonathantneal commented Jan 17, 2017

We need a heading element without implicit order. We need a heading element that can be updated without being replaced. Please consider <h>.

The <h> element is desired for situations where the “ranking” context changes for a heading, either before or after the source is sent to the browser. The current process of figuring out the appropriate “rank” of a heading is as unnecessary as requiring <li> to be <l1-n>.

Which also brings up a secondary point; there are not only 6 levels of headings.

So, please, please thoughtfully consider a single heading element like <h>, which would represent the heading for its section. The “rank” of such elements would be determined by outline depth.

If it helps, this addition might be developed on the shoulders of the XHTML 2 <h> element proposal, or @stevefaulkner’s html5-h proposal which answers to this bug. I believe Steve recognized that a fiction of the document outline was its retroactive impact on <h1-6> elements, which this new element would not be impacted by.

Should there be concerns regarding the time between specification and implementation, polyfills like the one The Paciello Group created would provide developers an appropriate and accessible fallback before the new element is widely adopted. Things like this have been done in similar situations, like with <picture> not being recognized in all browsers for a time, or with <nav role="navigation"> not being recognized with an implicit landmark.

@bkardell

This comment has been minimized.

Copy link

@bkardell bkardell commented Jan 17, 2017

If we're serious about this, I'd suggest working on a better polyfill and considering several things... @stevefaulkner was kind of proof of concepting it pretty early, and that was great, but it currently this uses polymer and from what I can see it is probably incomplete... Should probably just be vanilla v1 - It also could use some more thought/tweaking in implementation (should probably consider aria roles for sections maybe as well, probably not use imports, should work with dynamic mods/lifecycle, etc)... I agree this is kind of important, I use a build time process to do effectively the same thing for my blog in fact - another challenge is that the currently all or nothingness of it makes it hard... Like, if you also have an <h1>...<h6> somewhere in your page, it will be wonky.

@Marat-Tanalin

This comment has been minimized.

Copy link

@Marat-Tanalin Marat-Tanalin commented Jan 17, 2017

a fiction of the document outline was its retroactive impact on <h1-6> elements, which this new element would not be impacted by.

Exactly.

@jonathantneal

This comment has been minimized.

Copy link
Author

@jonathantneal jonathantneal commented Jan 18, 2017

If we're serious about this, I'd suggest working on a better polyfill

That’s fair. Here is a speculative polyfill: http://codepen.io/jonneal/details/wgombw/

consider aria roles for sections

I expect to rely on existing expectations; following what browsers and a11y tools already interpret when, say, a [role="section"] contains a [role="header"]. Backwards compatibility with existing apps should be paramount.

Relevant: https://www.w3.org/TR/html5/sections.html#outlines

@chaals

This comment has been minimized.

Copy link
Collaborator

@chaals chaals commented Feb 6, 2017

This is a really common request for HTML. The use cases seem clear, there have been several attempts to make it happen, and it would seem helpful.

Is there evidence of widespread usage of polyfills to make it happen in practice?

@Marat-Tanalin

This comment has been minimized.

Copy link

@Marat-Tanalin Marat-Tanalin commented Feb 6, 2017

Fwiw, when I need a levelless heading, I currently use either DL element (just to exploit its DT as a heading):

<section><dl>
	<dt>Heading</dt>
	<dd>
		<p>Some content.</p>
	</dd>
</dl></section>

or a bare HEADER (not quite correct, but it at least has similar/related semantics):

<section>
	<header>Heading</header>
	<p>Some content.</p>
</section>

In both cases, HTML validator, as expected, complains of that the section lacks heading.

The usecases include e. g. a heading for each of sections in a sidebar [1], or for an aside block that is placed after article text, intended for printing and contains a list (index) of all links used in the article [2].

[1] http://tanalin.com/en/about/
[2] http://sergeytroshin.ru/articles/windows-7-tweaking/

Also, considering the forever-weird magic behind the existing LEGEND element, as well as the fact that it is only intended for FIELDSETs and cannot be used for forms themselves, I would like to use a new levelless-heading element (free of any legacy magic) in such cases instead of LEGEND.

@jonathantneal

This comment has been minimized.

Copy link
Author

@jonathantneal jonathantneal commented Feb 7, 2017

Okay, let’s make this happen. I’ve written a specification proposal for a contextual heading <h> element:

https://rawgit.com/jonathantneal/h-element-spec/gh-pages/

I’ve written a speculative polyfill that gives the appropriate role="heading", aria-level="n", and <h1-6>-like styles to contextual heading elements (using a custom element namespace) in real-time:

https://github.com/jonathantneal/hfill

I’ve written a postcss and posthtml plugin that would allow you to use and style contextual headings JavaScript-free.

https://github.com/jonathantneal/postcss-hfill
https://github.com/jonathantneal/posthtml-hfill

@rubencodes

This comment has been minimized.

Copy link

@rubencodes rubencodes commented Feb 7, 2017

I haven't had my morning coffee so this took me a minute to grok.

I think when most people think about <h[x]> elements, x denotes the prominence on the page of the heading, but here you're more talking about the interpreted semantics of <h[x]>, yes? If so, totally agree and seems like outline depth is a good measure, assuming it's relative to the rest of the <h> tags on the page.

@pxsmith

This comment has been minimized.

Copy link

@pxsmith pxsmith commented Feb 7, 2017

This is quite sensible. 👍

@LJWatson

This comment has been minimized.

Copy link
Collaborator

@LJWatson LJWatson commented Feb 7, 2017

Thanks for the proposal and polyfill @jonathantneal

@domjtalbot

This comment has been minimized.

Copy link

@domjtalbot domjtalbot commented Feb 7, 2017

Awesome idea @jonathantneal, seems quite logical!

How about <heading> as a more semantic approach, perhaps? 💭

@pepelsbey

This comment has been minimized.

Copy link

@pepelsbey pepelsbey commented Feb 7, 2017

You can’t always control you modules/blocks nesting while using templating or partials systems. It’s too easy to make a mistake or get caught in a nesting you can’t possibly control. That’s why explicit heading levels numbering is so useful. <h> would be as fragile as nesting-based languages though we used to think about HTML as bullet-proof markup that will always forgive us all mistakes.

@pxsmith

This comment has been minimized.

Copy link

@pxsmith pxsmith commented Feb 7, 2017

@domjtalbot first of all, <header> is six letters longer than <h>. 😂 But on a serious not, it seems like HTML5 Doctor suggests using <header> as a wrapper for <h1>, <h2, etc. I was wondering that, myself, about using <header>—glad you asked the question.

@chaals

This comment has been minimized.

Copy link
Collaborator

@chaals chaals commented Feb 8, 2017

@pepelsbey

You can’t always control you modules/blocks nesting while using templating or partials systems. It’s too easy to make a mistake or get caught in a nesting you can’t possibly control.

The way I think - e.g. when you are trying to write content that will drop into someone else's template or page, being able to use nested sectioning/h elements and have the outline generated automatically is a positive thing. That's why it has been proposed for XHTML2, included in HTML 5 despite no implementation, and why it keeps coming up as a request.

So I don't understand your conclusion, which seems to be the opposite - if you have the nesting calculated for you, something will go wrong.

Or did I just misunderstand?

@pepelsbey

This comment has been minimized.

Copy link

@pepelsbey pepelsbey commented Feb 8, 2017

@chaals, you're coming from optimistic conclusion that outline is always correct and everyone knows what they are doing. But since outline is just and idea existing only in the spec, but not in browsers, developers’ minds or real-life code, I'm inclined to think that it's wrong by default and as an author of a module you can't control the proper nesting level. I wouldn't rely on outline when <section> is just a new fancy <div>.

@stevefaulkner

This comment has been minimized.

Copy link
Contributor

@stevefaulkner stevefaulkner commented Feb 8, 2017

@chaals @pepelsbey I agree, the heading level being reliant upon the nesting of article and section elements is problematic because there is no requirement that either include a child heading and the outline algorithm does not take into account section/article elements which do not contain child headings.

for example

<h1>heading</h1>
<section>
<section>
<section>
<h1>heading</h1>
</section>
</section>
</section>

results in
h1
h3

And this is not a theoretical markup pattern, there are plenty of examples in the wild where multiple nesting of section elements can be found. will provide some later.

@stevefaulkner

This comment has been minimized.

Copy link
Contributor

@stevefaulkner stevefaulkner commented Feb 8, 2017

252 HTML5 pages using the section element

The following pages are a subset of pages that use the HTML5 doctype that also use the section element. The section elements have been styled to indentify section elements and section element nesting (up to 2 deep).
http://www.html5accessibility.com/HTML5data/section/section.html

@LJWatson

This comment has been minimized.

Copy link
Collaborator

@LJWatson LJWatson commented Feb 8, 2017

@stevefaulkner broken heading hierarchies happen routinely with numbered headings already, chiefly because developers choose headings based on factors other than their semantic importance. So in this regard, this proposal probably doesn't gain us much ground - we're likely to end up with broken heading hierarchies whichever way we go.

As an aside, I wonder whether the conformance validator would be better able to detect errors in sectioning as opposed to heading numbering? Ping @sideshowbarker

But the appeal of this proposal is that it seems to provide a way to solve the content reuse problem. Drupal is a good example: it uses panes of content to construct templates, and a pane can be reused across multiple templates - each of which may have a different heading hierarchy. Right now it's next to impossible to maintain robust heading hierarchies across multiple templates unless you have a website of draconian simplicity.

So given an equal playing field (a developer who understands both heading hierarchy and sectioning hierarchy), the <h> proposal would seem to solve a relevant problem for content reuse.

@nico3333fr

This comment has been minimized.

Copy link

@nico3333fr nico3333fr commented Feb 8, 2017

Even if the idea is really not bad, I see a lot of cases where it will fail. Consider this code :

<section>
  <h>Lorem Ipsum<h>
  …
  <h>Dolor si amet<h>
  …
  <h>Consegur<h>
  …
  <h>Blahblah<h>
  …
  <h>Blahblah 2<h>
  …
</section>

How do the browser will know that it means :

<section>
  <h2>Lorem Ipsum<h2>
  …
  <h3>Dolor si amet<h3>
  …
  <h3>Consegur<h3>
  …
  <h2>Blahblah<h2>
  …
  <h3>Blahblah 2<h3>
  …
</section>

or

<section>
  <h2>Lorem Ipsum<h2>
  …
  <h2>Dolor si amet<h2>
  …
  <h3>Consegur<h3>
  …
  <h3>Blahblah<h3>
  …
  <h4>Blahblah 2<h4>
  …
</section>

Etc.

In fact, this idea (even if I find it really cool) moves the problem of the Hx-outline to landmarks (section, header, etc.). If so many sites are already failing to provide a correct Hx structure, I really fear that they won't be able to do better using landmarks.

@SebastianZ

This comment has been minimized.

Copy link

@SebastianZ SebastianZ commented Feb 8, 2017

I assume this requires to nest them in subsections, e.g.

<section>
  <h>Lorem Ipsum<h>
  …
  <section>
    <h>Dolor si amet<h>
    …
    <h>Consegur<h>
    …
  </section>
  <h>Blahblah<h>
  …
  <section>
    <h>Blahblah 2<h>
    …
  </section>
</section>

Additionally an optional attribute level could be introduced allowing to overwrite the level defined by nesting, e.g. <h level="3">. That's more verbose than <h3>, but cleaner, because the level is considered as attribute of the heading and fits well into the nesting concept.

Sebastian

@Heydon

This comment has been minimized.

Copy link

@Heydon Heydon commented Feb 8, 2017

@SebastianZ @nico3333fr

Yes, I believe the proposal is just for when sectioning elements are employed. You would use equivalent heading levels if sectioning elements were not employed.

@AndySky21

This comment has been minimized.

Copy link

@AndySky21 AndySky21 commented Feb 8, 2017

@nico3333fr,
is it really necessary to consider such a case?
I have been reminded that authors don't read specs and this can be right or wrong, but I strongly think that there are structures whose meaning is unquestionable.

<section>
  <h>Lorem Ipsum<h>
  …
  <h>Dolor si amet<h>
  …
  <h>Consegur<h>
  …
  <h>Blahblah<h>
  …
  <h>Blahblah 2<h>
  …
</section>

Ages of simple markup have taught us that elements of the same type in the same level mean the same, so if authors wants deeper levels they will have to use nesting sections.

Authors are not that dumb. Otherwise structures like nested lists (which present the same issue) wouldn't even be possible. They will understand that the choice is to sacrifice immediacy of semantics (given by numbered headings) or simplicity of markup (and thus nest sections), but not both.

@SebastianZ, I think that using a level attribute would have the same issues of explicit <h#> elements. What happens when content is reused or authors break the order chain? It should be stated that numbers have no value meaning but they only serve for relative ordering. I.E. <h level="y"> is to be considered a deeper outline level than <h level="x"> when x < y, regardless of actual values.
This is not a scenario I'd like to see when resources start being shared, because it would involve authors' skills and content stability to a deeper level than I'm going to trust...

@Heydon

This comment has been minimized.

Copy link

@Heydon Heydon commented Feb 8, 2017

Some thoughts regarding the CSS part:

Obviously, nobody wants to write

section section section h { font-size: x }

for an h4. Also, it becomes highly complex when you have to consider all the combinations of sectioning element, like

section article section h,
article section article h,
article article section h,
section article article h,
article article article h,
etc {
  font-size: x;
}

In which case, I would propose that heading element selectors acted as aliases for nesting depth.

So

h2 {
   font-size: x;
}

would effectively be

h2, 
section h, 
article h, 
aside h, 
nav h {
  font-size: x;
}
@jakearchibald

This comment has been minimized.

Copy link

@jakearchibald jakearchibald commented Feb 8, 2017

Why is this proposal better than the current <h1> + <section> + outline algorithm?

@jakearchibald

This comment has been minimized.

@Heydon

This comment has been minimized.

Copy link

@Heydon Heydon commented Feb 8, 2017

@jakearchibald My first thought is that the "<h1>s everywhere" idea was much vaunted to begin with, followed by widespread retractions when folks worked out that the outline algorithm didn't exist. In which case, maybe there's something to be said for stepping away from that car wreck and getting a new car, to use a mangled analogy.

Yeah, :any() helps, but I think the alias thing would be sweeter (if not likely to incur performance issues).

@jakearchibald

This comment has been minimized.

Copy link

@jakearchibald jakearchibald commented Feb 8, 2017

@Heydon I get that the outline isn't implemented, but neither is <h>. This proposal needs to state why it's more likely to succeed than what we already have + implementation of the outline.

@AndySky21

This comment has been minimized.

Copy link

@AndySky21 AndySky21 commented Feb 8, 2017

@jakearchibald, I think that relying upon section + h1 was a mistake because it implied a new use for an existing element. Which proved wrong when h1 headings ended up being used everywhere without the outline algorithm

On the other hand, a brand new element would have no meaning outside of said algorithm or without a proper polyfill, which reduces misuses.

@jonathantneal

This comment has been minimized.

Copy link
Author

@jonathantneal jonathantneal commented Mar 8, 2017

I’m thankful for this conversation and agree with @jakearchibald & @bkardell on next steps. I’ll continue efforts into outline and h-element-spec. Since I opened it, I think I can close this issue based on the tags needs implementations and needs incubation. For future reference: I’d encourage someone else to either re-open this or start a new issue once there’s significantly more evidence to discuss.

Oh, and one more thing, @bkardell.

Work together on getting good polyfills for any of these proposals, even the ideas you maybe don't particularly like/support.

You have my sword.

@danieltj27

This comment has been minimized.

Copy link

@danieltj27 danieltj27 commented Apr 26, 2018

What's the progress on this thus far? I've checked out the h-element-spec repository but looks like there's not been any movement since early February. Is this any particular path we need to take now or a way to keep things moving? I'm curious on how we can keep this going and on the road to making it 'official'.

@Dan503

This comment has been minimized.

Copy link

@Dan503 Dan503 commented Jan 7, 2019

There seems to be a bit of a misconception of what introducing the <h> element would mean in terms of how developers would use it.

It's not a case of either using <h> for everything or <h1>-<h6> for everything. The idea would be to use the <h> element and the numbered <h#> elements together.

The <h> element would basically be a replacement for the <h1> element in the document outline algorythm. This is more of a "use <h1> or use <h>, don't use both" sort of situation. The rest of the numbers are fair game though. If the browser detects a <h> element then it knows that it needs to use the document outline algorithm. If there are no <h> elements then it uses the legacy <h1-6> heading structure method. This avoids all the legacy baggage that comes with using the <h1> element.

Reading the spec on <h#> elements, if the <h1> element is replaced with <h>, then the two code samples below would be equivalent.

<article>
  <h>Article title</h>
  <p>Lorem ipsum</p>

  <h2>A secondary heading</h2>
  <p>Lorem ipsum</p>

  <h3>A tertiary heading</h3>
  <p>Lorem ipsum</p>

  <section>
    <h>heading</h>
    <p>Lorem ipsum</p>
  <section>
</article>

That is equivalent to writing this:

<article>
  <h>Article title</h>
  <p>Lorem ipsum</p>

  <section>
    <h>A secondary heading</h>
    <p>Lorem ipsum</p>

    <section>
      <h>A tertiary heading</h>
      <p>Lorem ipsum</p>
    </section>

  </section>

  <section>
    <h>heading</h>
    <p>Lorem ipsum</p>
  <section>
</article>
@LJWatson

This comment has been minimized.

Copy link
Collaborator

@LJWatson LJWatson commented Jan 7, 2019

@Dan503

This comment has been minimized.

Copy link

@Dan503 Dan503 commented Jan 7, 2019

I think the instant the browser detects a <h> element anywhere on the page it signals that the browser should use the document outline algorithm for creating the document outline.

So <h1> and <h> essentially serve the same purpose as long as at least one <h> is used.

@Dan503

This comment has been minimized.

Copy link

@Dan503 Dan503 commented Jan 7, 2019

...actually this is starting to sound silly.

The <h> element isn't needed. What is needed is a way to tell the browser "I know what I'm doing, I'm a new website, let me use the outline algorithm".

For that all we really need is an outline attribute added to the html element. If the attribute exists, the page will be outlined using the algorithm. If not, the outline will be generated the old fashioned way.

No changes need to be made to the document outline spec other than mentioning this new attribute. So there is less work involved in adding an attribute over adding a <h> element.

I also like the idea someone brought up that it is better for a non-supporting browser to fall back to a heading than to fall back to a <span>.

@Dan503

This comment has been minimized.

Copy link

@Dan503 Dan503 commented Jan 7, 2019

A <meta> element in the <head> would also work.

@viT-1

This comment has been minimized.

Copy link

@viT-1 viT-1 commented Jan 8, 2019

<article> <h>Article title</h> <p>Lorem ipsum</p> <h2>A secondary heading</h2>

Do you mean <h1>Article title</h1> ?

@viT-1

This comment has been minimized.

Copy link

@viT-1 viT-1 commented Jan 8, 2019

For backward compatibility:

<label for="someArticle" role="heading">Main heading</label>
<article id="someArticle">
  <label for="someSection" role="heading">Some heading</label>
  <section id="someSection">
    <label for="innerSection" role="heading">Other heading</label>
    <section id="innerSection">
    </section>
  </section>
</article>

or

<article id="someArticle">
  <label for="someArticle" role="heading">Main heading</label>
</article>

Old label is a sort of heading with additional accessability feature - changing the cursor focus! ;)

@Dan503

This comment has been minimized.

Copy link

@Dan503 Dan503 commented Jan 8, 2019

Do you mean <h1>Article title</h1>?

When I wrote that comment, I meant what I said.

But in writing that comment, I realised how silly the <h> element would be when <h1> elements in combination with either an attribute or a meta tag would be better.

If you replace the <h> elements with <h1> elements in that example then you basically have what the current HTML5 spec says.

@Dan503

This comment has been minimized.

Copy link

@Dan503 Dan503 commented Jan 8, 2019

@viT-1 would you really prefer to write a gazillion ID's that all need to be unique in every different context that they are used than nest heading elements inside sectioning elements?!?

@viT-1

This comment has been minimized.

Copy link

@viT-1 viT-1 commented Jan 8, 2019

@Dan503 If "label" haven't attribute "for" it can be matched by "sections" nesting, but how can it be matched if h/label not on a first nesting level of DOM? Calculate h-level only by "section" elements?

@jonathantneal

This comment has been minimized.

Copy link
Author

@jonathantneal jonathantneal commented Jan 8, 2019

@danieltj27, I stopped working on the proposal for a number of selfish reasons. First, I can be very unfocused and easily discouraged. Second, Google and Bing correctly displayed headings with <h> at the time — I don’t know why — so I didn’t need to wait. One can pair it with role="heading" and aria-level either pre-compiled or post-compiled and let one’s SEO expert see the results for themselves. Another solution is to let tooling change h into h1 through h6 automatically. Either way, be sure you trust your solution to work for accessibility tooling. Third and finally, maybe it was just a bad idea. I think Jake thought it was a bad idea, and I thought he made quality arguments against it. Plus, it seemed like a dumb career move to be this relatively unknown dev now known for a crappy idea that had to be dismantled by a more respectable dev. Also, I think one of my posts was described as self-congratulating, so I think I was maybe doing a crappy job communicating a possibly stupid idea. Yea, no thanks, I hope I’m just here to help.

@Dan503, yea using <h1> for backwards compatibility solution seems cool, too. It still solves the problem of not wanting to mentally or programmatically manage heading levels.

I’m just getting back from vacation this morning, so I hope y’all will forgive me for not including citations.

@viT-1, definitely look at aria-level in addition to role="heading", even though I’m not a fan of redefining label. Also, look at the study that showed how useful heading levels were to users of accessibility tooling.

@Dan503

This comment has been minimized.

Copy link

@Dan503 Dan503 commented Jan 8, 2019

Calculate h-level only by "section" elements?

Yes, it is called the document outline algorithm. It is the whole reason for this issue because we want browsers to implement it.

You can learn more about it here:
https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Using_HTML_sections_and_outlines

@dskoziol

This comment has been minimized.

Copy link

@dskoziol dskoziol commented Jan 8, 2019

@jonathantneal : I'm not sold on having an <h> element, and I think Jake's reasoning for using <h1> everywhere is sound. I am, however, very interested in the speculative polyfill you made above (hfill). I haven't tried it out, but if that kind of thing works on screen readers now, (assigning aria-level to override default h# semantics, then if we rewrite and polish your polyfill to work on multiple h1s with sectioning elements, we could be using multiple h1s today and have it all work properly for people who rely on screen readers. Then when (or if) the document outline algorithm is properly implemented, we can drop it. This would make maintainability a whole lot easier and help lead to a more accessible web (I personally find it very difficult to maintain proper h# numbering when I'm working on projects with multiple partials and layouts, especially if the same partial is used in different places and needs different numbering depending on its context).

That all depends on if <h1 aria-level="2"> is functionally identical to <h2>, which I don't know enough about to answer.

What do you think?

@jonathantneal

This comment has been minimized.

Copy link
Author

@jonathantneal jonathantneal commented Jan 8, 2019

@dskoziol, yes hfill could be retooled for this. Also, I think Brian was collecting different implementation ideas, too. @bkardell, would you mind sharing those links or what you’ve learned since experimenting in this space?

@dskoziol

This comment has been minimized.

Copy link

@dskoziol dskoziol commented Jan 8, 2019

Additionally, as you've written, we could use the polyfill to swap out h1s with h2s and such, but I think relying on aria-level would be a lot nicer because devs could pop it in and it would just work, as opposed to changing h# which would potentially mess with visual styling that they've written

@Dan503

This comment has been minimized.

Copy link

@Dan503 Dan503 commented Jan 8, 2019

From the screen reader testing I have done in NVDA, aria-level does overide the default implied level.

Eg. <h1 aria-level="3"> is read out as a <h3> element.

@Dan503

This comment has been minimized.

Copy link

@Dan503 Dan503 commented Jan 8, 2019

By the way, I love the idea of hfill just being a drop in polyfill for the document outline algorithm powered by real heading elements 😊

@dskoziol

This comment has been minimized.

Copy link

@dskoziol dskoziol commented Jan 8, 2019

Totally! If there are no issues with it, I'd start using it everywhere right away.

@aardrian

This comment has been minimized.

Copy link

@aardrian aardrian commented Jan 8, 2019

Note that browser makers have not implemented the document outline algorithm as proposed generally because it requires too much complexity when faced with real content. That is part of the reason the document outline algorithm never made it into the final W3C specification.

Part of the challenge is dealing with highly-nested sections, thanks to tooling that treats <section> or <article> the way <div> is handled as highly-nested layout elements. Part is due to not knowing the meaning of the content and what really should be nested under which.

Before proposing a new element, the document outline algorithm needs to be mapped and defined in a way that browsers will implement. A polyfill can do that. Create the proof of concept in a polyfill and then elevate that as a proposed rule-set to W3C. Whether it is encoded as an <h> or <hammer> will not matter.

Definitely do not use <label>. It has a very specific purpose and is supported in known and consistent ways across tools and browsers. Rejiggering it to a new purpose will only create an accessibility pit.

@jonathantneal

This comment has been minimized.

Copy link
Author

@jonathantneal jonathantneal commented Jan 8, 2019

Here’s a link to a comparison of 3 different document outline solutions as they would apply to a dozen different content patterns: https://bkardell.com/outline/

@Dan503

This comment has been minimized.

Copy link

@Dan503 Dan503 commented Jan 9, 2019

https://bkardell.com/outline/compare.html

Use case 1, Outline proposal polyfill

<h1>Some articles</h1>
<article>
  <h3>This is an old legacy article</h3>
  <p>It's stored in a CMS and assumes headings start at h3.</p>
  <h4>But then the template changed!</h4>
  <p>The site wanted to make use of nested sections, but this content should still work.</p>
</article>

But then the template changed!

The polyfill makes that out as a <h2> but that is not inline with the document outline algorithm as it has been written.

<article>
  <h1>heading one</h1>
  <p>lorem ipsum</p>

  <h2>heading two</h2>
  <p>lorem ipsum</p>
</article>

The outline algorithm says that the above is the equivalent of writing this:

<article>
  <h1>heading one</h1>
  <p>lorem ipsum</p>

  <section>
    <h1>heading two</h1>
    <p>lorem ipsum</p>
  </section>
</article>

Currently the polyfill seems to be doing this instead:

<article>
  <h1>heading one</h1>
  <p>lorem ipsum</p>

  <h1>heading two</h1>
  <p>lorem ipsum</p>
</article>

That is incorrect.

In other words, "But then the template changed!" heading should be turned into a <h3> using the polyfill, not a <h2>.

(Is there a better place for issues like this to be logged?)

@SelenIT

This comment has been minimized.

Copy link

@SelenIT SelenIT commented Jan 9, 2019

In my opinion, it's probably time to admit that the concept of "HTML5 document outline" based on the "sectioning content" nesting level has failed, and further discussing of hypothetical ways to "fix" it is quite pointless. Especially in the W3C HTML repo, given that, AFAIK, HTML5.3 is not going to become W3C Rec. It has been years since W3C and most HTML evangelists started to discourage relying on this "fictional" outline. Let's face the cruel reality: the "HTML5 document outline" is effectively dead.

Instead, I suggest to open an issue against the WHATWG HTML repo about retiring the "document outline" concept (as effectively irrelevant to any practical application) and redefining the current "Sectioning content" elements solely in terms of ARIA Landmark roles mapping. (Upd.: it has already been discussed there). This is way more practical (since the corresponding mappings are widely supported by virtually all modern browsers) and it would simplify the mental model of these elements for the authors a lot, making these element follow the single responsibility principle and eliminating the confusion about <main> element not being "Sectioning content" despite its obvious similarity to e.g. <aside> element from the author's perspective.

After that, we would be free to investigate the possibilities to create better – more flexible and descriptive – outlines for future documents only, without any backwards compatibility concerns. We could account for @AmeliaBR's note that heading levels in the same context can be used to express the relative importance of the same-rank sections. It could be a completely new element with a single functionality of creating separate contexts in the outline, or an attribute for existing grouping elements – whatever would be easier for implementation...

@dickensian

This comment has been minimized.

Copy link

@dickensian dickensian commented Jan 9, 2019

You are entitled to your opinion

@Dan503

This comment has been minimized.

Copy link

@Dan503 Dan503 commented Jan 9, 2019

The outline algorithm is too good and has had too much work go into it to just give up on it and with how modular focused the web has become it's more important than ever that it get implemented by browsers.

@jakearchibald

This comment has been minimized.

Copy link

@jakearchibald jakearchibald commented Jan 9, 2019

The latest work on a simplified algorithm is at whatwg/html#3499

@SelenIT

This comment has been minimized.

Copy link

@SelenIT SelenIT commented Jan 9, 2019

@Dan503, exactly because the outline algorithm itself is good and too important for the modular web, I suggest to try more realistic options to make it real than persuading browser vendors who have been rejecting the requests to implement it for years to change their mind by continuing a discussion in a closed issue to a (de facto) discontinued spec:(

@jakearchibald, thanks a lot for a link to the latest work!

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
You can’t perform that action at this time.