Join GitHub today
GitHub is home to over 50 million developers working together to host and review code, manage projects, and build software together.Sign up
Add heading-focused outlines and :heading #3499
This makes a number of fairly big changes:
/acknowledgements.html ( diff )
As far as the algorithm at https://whatpr.org/html/3499/sections.html#heading-level that assigns levels to headings, I think that for some normal cases of
For example, consider the following document:
Given the above, the algorithm at https://whatpr.org/html/3499/sections.html#heading-level assigns a heading level of
It doesn’t seem at all intuitive for the title to be assigned a heading level of
I don’t think authors/developers would expect that title to be a level
As far as
The original/current purpose of
So in that model, it was necessary to ensure that a (conceptual) subsection would not be created by a heading an author intended as a subheading. Thus in the outline algorithm, that’s the effect
But if we dispense with the conceptual model of headings creating subsections (as the patch in this PR branch does), then we no longer need a way to prevent a heading from creating a subsection. So we need longer need
And if we don’t have
And if we drop
In other words, instead of using
So I think the vast majority of authors who are using subheadings in their documents aren’t going to care whether we drop
But all that said, I don’t feel strongly that we must drop
However, I do feel strongly that if we keep
To reinforce the points I made in #3499 (comment) about
…and changes it to this:
On the face of it the phrase prevent the
What I mean is, the
So it’s unclear what that explanation prevent the
So I think that argues for dropping the
As a note to @sideshowbarker's comment:
I understand that using
In my opinion what we have now is a badly designed
“Scoped to the
What I would have liked to have: An element for site-oriented content, say
w3c chose to add a section on subheadings etc. for common idioms without dedicated elements.
A new element
This makes a number of fairly big changes: * Introduces a heading and heading level concept. * Replaces the outline algorithm with a document headings concept. * Requires document headings to not skip heading levels and start with heading level 1. * Introduces a :heading pseudo-class selector. * Introduces a :heading(level) functional pseudo-class selector. * Does away with the section concept (except insofar it's needed to influence the heading level of h1/hgroup). * Does away with sectioning roots. Tests: ... Fixes #83.
Thanks everyone for your feedback! Given the concerns raised regarding
As I outlined in w3c/csswg-drafts#1008 (comment) there's also a valid concern with
I'm hopeful the change to
/cc @muan who has in the past raised concerns that this would not suffice for GitHub's use case.
If I recall correctly, the ask was to be able to wrap user-generated content in an
<h1>GitHub</h1> <h2>jsdom/jsdom</h2> <article> <h1>jsdom</h1> <h2>Basic usage</h2> <h2>Customizing jsdom</h2> <h3>Simple options</h3> ... </article>
I'm unsure whether that's feasible given the constraints on simplicity that this PR is working toward, but I want to ensure that if we're excluding this use case, that we do so on purpose.
Going through previous sibling might not be that bad (though it is certainly worse than counting ancestors), but I suspect the need is even more complicated and would need to cover cases such as
<article> <h1>jsdom</h1> <h2>Basic usage</h2> <div><h2>Customizing jsdom</h2></div> <h3>Simple options</h3> ... </article>
as well, at which point it becomes unworkable. (Also known as the unstated algorithm in the standard today, roughly.)
I'm not familiar enough with the details of what's happening to tell why inserting a
Edit: hmm, defining "most-recently-seen heading level" in a timeless way makes the difficulties more apparent. E.g. in cases like
<h1>GitHub</h1> <h2>jsdom/jsdom</h2> <div> <article> <h1>jsdom</h1> <h2>Basic usage</h2> <h2>Customizing jsdom</h2> <h3>Simple options</h3> ... </article> </div>
(which I believe is more realistic with regard to GitHub's actual markup) do not provide any easy way of finding
I'm a little bit concerned about if this idea breaks the meaning of the
Article is meant to be a self contained piece of content that can make sense on its own when taken out of context.
Does this idea go against the fundamental meaning of what the
I do like the idea in general though so maybe
Thanks @domenic for mentioning our issue. I've been quietly following the thread and can see how this is all complicated, so haven't been able to add anything.
I don't know if introducing a new element will solve this since what algorithmically couldn't be done for
I might be way off– could introducing a new attribute, to make "most-recently-seen heading level" explicit, work?
<h1>GitHub</h1> <h2>jsdom/jsdom</h2> <div> <article headinglevelstart="3"> <h1>jsdom</h1> <h2>Basic usage</h2> <h2>Customizing jsdom</h2> <h3>Simple options</h3> ... </article> </div>
Since the alternative is generating markup that has the explicit
I like your idea @muan it is reminiscent of how
This also might help solve the problem of nested sections labelled with
We don't have to move
This is how I imagine it working:
Without the attribute:
<body> <h1>Read as h1 :)</h1> <p>content</p> <aside> <section> <h1>This is read as a h3 :(</h1> <p>content</p> </section> <section> <h1>Also read as a h3 :(</h1> <p>content</p> </section> </aside> </body>
With the attribute:
<body> <h1>Read as h1 :)</h1> <p>content</p> <aside headinglevelstart="1"> <section> <h1>This is read as a h2 :)</h1> <p>content</p> </section> <section> <h1>Also read as a h2 :)</h1> <p>content</p> </section> </aside> </body>
<body> <!-- heading levels ignore sectioning elements --> </body>
<body headinglevelstart="1"> <!-- heading levels are affected by sectioning elements --> </body>
Just implementing this algorithm directly into browsers across all websites across the whole world would break backwards compatibility.
I've had a better idea about this. It can be explicitly written in the spec that if a sectioning element does not have a heading element associated with it, then it does not affect heading levels. That would probably be much easier and also much less likely to break backwards compatibility
<body> <h1>Read as h1</h1> <p>content</p> <!-- no heading element association so heading levels are not incremented --> <aside> <section> <h1>This is read as a h2 :)</h1> <p>content</p> </section> <section> <h1>Also read as a h2 :)</h1> <p>content</p> </section> </aside> </body>
I still like the
I disagree with this assessment. Lots of WordPress themes I|ve visited encompass a post inside a main inside an article, and the comments are outisde the article, but inside the main. The h1 that contains the blog post title is in all these cases remapped to a level 2, which is wrong, since it is then put in line with h2s inside the post that denounce sub sections. And those pages then no longer have an h1 alltogether.
Further, one of the major news sites for IT topics in Germanz, Heise, uses articles as well, putting their h1 out of service.
The Moyilla instance of Bugyilla|s view bug page breaks, no longer has an h1 as well.
And I|ve seen others, which I forgot to take notes about, but to me, this seems prettz significant. The breakage inflicted on WordPress blogs alone is prettz substantial.
I agree with @MarcoZehe. I raised this before in #83 (comment): main headings in default WordPress themes, e.g. Twenty Fifteen, are inside
<body> […] <main> <article> <h1>Blog post heading</h1> </article> </main> […] </body>
I downloaded the newest Firefox Nightly and tested it on several WP sites (including mine) and Firefox treats such heading as level 2 one – so the main heading of the page is removed in the process.
However this pattern is not common only in the context of WordPress and its default themes, it is also present in many tutorials about basics of HTML and accessibility (including mine ;)) – at least in Poland.
I see two possible solutions for this issue:
I would much rather an opt-in mechanism. It is far less likely to result in bugs that are impossible for the developer to fix outside of forcing it with an
The second option you gave doesn't really work if there is a left sidebar on the page with a heading in it. The sidebar heading would be encountered first so it would become the
@MarcoZehe yeah, I clearly wrote that too quickly. If reporting some h1s as level 2 is considered too much breakage we should make the standard reflect the status quo of h1-h6, even if it makes the default styling for some elements rather weird. Not sure what it means for hgroup, I guess it'll remain a container of sorts.
@annevk it appears from https://groups.google.com/d/msg/mozilla.dev.platform/SdnMKYwWxzU/U-v_b8c2BwAJ that this was not able to be implemented. Should we abandon this approach, and instead update the outline algorithm to just assemble an outline based on h1-hN, and update all the examples in the spec accordingly?
I guess we may still want to build it on top of this PR, since you've done a lot of the work to remove concepts like sectioning roots, etc.