HTML heading levels

[Rob Beezer]

For those using screenreaders, the HTML elements #h1 through #h6 are important
for navigation. Since we can produce HTML files at various chunk levels, it is
no simple matter to try to get these right. We have been doing a good job with
these, but I asked Claude Code to take a look at improvements.

Not easy for Claude. I'll say it failed three times. (Once by hitting a rate
limit and losing the conversation.) Took most of my day baby-sitting it.
Interesting nonetheless. But I'll say the result is a definite improvement for
the output, for reliability, and for maintenance, though it litters a whole lot
of templates with additional parameter passing (162 more of them!).

Real point for writing. PR available at:

https://github.com/PreTeXtBook/pretext/pull/2851

Alex and Haris most recently got mixed up with this code - comments welcome.
I'll merge this pretty quick, its going to bitrot quickly.

Rob

[Charilaos Skiadas]

I didn’t check all the details but I think the overall plan is reasonable. The gist of it for me is that attempting to compute the correct heading level by tracking down parents is cumbersome and error-prone on the best of cases, and in the absence of something akin to React ContextProvider we simply have to accept a possibly excessive but very straightforward passing down of the heading-level variable. A bit more verbose but simpler.

Maybe also more efficient?

And also sounds like it is somewhat future-proof in that any new added templates that forget to account for the heading-level will generate PTX-BUGs.

The only thing that bothers me a tad is that the changes bled into pretext-common. But I guess the alternative is to override those templates in pretext-html just for this addition.

I am assuming this doesn’t affect other renderings that use pretext-common? They just pass around for a bit a variable that has no use for them.

Charilaos Skiadas
Department of Mathematics
Hanover College

--
You received this message because you are subscribed to the Google Groups "PreTeXt development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pretext-dev...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/MTAwMDAzNC5iZWV6ZXI.1778715247%40pnsh.

[Rob Beezer]

Thanks, Haris, for having a look, since you are familiar with this part of the code.

> A bit more verbose but simpler. Maybe also more efficient? And also sounds
like it is somewhat future-proof in that any new added templates that forget to
account for the heading-level will generate PTX-BUGs.

All part of my (long) conversation with Claude. ;-)

> The only thing that bothers me a tad is that the changes bled into
pretext-common.

Me too. But I do think it is harmless, an uninteresting value will just get
passed along. Those templates for #sidebyside and #sbsgroup are good to have
"down" in -common, and they should be passing along this information to their
contents.

Rob

On 5/14/26 10:14, Charilaos Skiadas wrote:
> I didn’t check all the details but I think the overall plan is reasonable. The
> gist of it for me is that attempting to compute the correct heading level by
> tracking down parents is cumbersome and error-prone on the best of cases, and in
> the absence of something akin to React ContextProvider we simply have to accept
> a possibly excessive but very straightforward passing down of the heading-level
> variable. A bit more verbose but simpler.
> Maybe also more efficient?
> And also sounds like it is somewhat future-proof in that any new added templates
> that forget to account for the heading-level will generate PTX-BUGs.
>
> The only thing that bothers me a tad is that the changes bled into pretext-
> common. But I guess the alternative is to override those templates in pretext-
> html just for this addition.
> I am assuming this doesn’t affect other renderings that use pretext-common? They
> just pass around for a bit a variable that has no use for them.
>
> Charilaos Skiadas
> Department of Mathematics
> Hanover College
>
>

>> On May 13, 2026, at 7:34 PM, 'Rob Beezer' via PreTeXt development <pretext-

> to pretext-dev...@googlegroups.com <mailto:pretext-
> dev+uns...@googlegroups.com>.

> To view this discussion visit https://groups.google.com/d/msgid/pretext-

> dev/7E47B778-FF0B-4BA5-A263-54BE875BF8DF%40gmail.com <https://groups.google.com/
> d/msgid/pretext-dev/7E47B778-FF0B-4BA5-A263-54BE875BF8DF%40gmail.com?
> utm_medium=email&utm_source=footer>.

[Rob Beezer]

These changes have been merged. The massive threading is definitely more
efficient (versus ancestor lookups), as I see a roughly 3% speed-up with the
sample article processing to HTML. (Thanks, Andrew, for the new profiling tools
at #2829!)

Full details at https://github.com/PreTeXtBook/pretext/pull/2851

* There are changes that are "corrections" to what we had before, mostly
exposed at extreme chunk levels (big and small).

* When you open a #xref knowl, some content gets displayed. We can't really
know what #hN level that content should have in advance, and the same content
could open in wildly different locations. I guess we could use JavaScript to
inspect the surrounding and rewrite the content? Forget I said that. Anyway,
we start at #h2, presumably so the content has room to nest before running out
of road at #h6.

* Slightly similar for standalone pages, but there we know the masthead has an
#h1 so starting at #h2 should be right.

Not relevant for pretext-announce I think, but will mention on pretext-a11y.

Rob

[Rob Beezer]

And I forgot to say:

We may get reports of a "BUG" warning when a heading level does not get passed
down through divisions, containers, and blocks, and so becomes lost. I suspect
some of these could be a result of illegal structure. The error report will
have a nice list of the ancestors (the structure), so be sure to look at that.
The ancestor list is a cute trick Claude taught me, and I might replicate into
the more general "location-report" template.

Rob

[Oscar Levin]

I am getting such things for slideshows.  It causes the nightly build to fail.  I can dive in and check more carefully later, but thought I'd mention it while I was thinking about it.

To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/MTAwMDAyNi5iZWV6ZXI.1779038033%40pnsh.

[Rob Beezer]

Thanks. Do the error messages suggest some element/container that is at fault?

[Oscar Levin]

Here is the relevant errors: https://github.com/PreTeXtBook/pretext-cli/actions/runs/25985726954/job/76382648009#step:13:319

To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/MTAwMDAxMS5iZWV6ZXI.1779075135%40pnsh.

[Rob Beezer]

Thanks! I'd guess that #slide needs to accept the heading parameter and pass it to its children, perhaps with an increment by 1.

Good chance I can get to it sometime tomorrow.

Rob

[Rob Beezer]

Yep, #slide needed adjustment. Above #slide, in the document hierarchy, it
appears that the #hN are hard-coded, and perhaps on the assumption #slideshow
has #section (not a requirment, I think). So we may have a hop in levels for a
#section-less #slideshow.

I have (all by myself) put in a rational fix for the current case, so nightlies
should build again. I may turn my assistant loose on the generalizations needed
for the #section-less case, but that is less urgent.

Thanks, Oscar, for maintaining the testing infrastructure, and catching this
one. On any given change, I don't always see all the lesser conversions that
might be affected.

Rob

[Rob Beezer]

And now, a complete audit of heading levels in the #slideshow output. A bit
messy - not horrible. Fixed up now. For details see

https://github.com/PreTeXtBook/pretext/pull/2864

Much better. Thanks, Oscar, for the help.

>>>> MTAwMDAxMS5iZWV6ZXI.1779075135%40pnsh
>>>> .
>>>>
>>>
>>
>

[Rob Beezer]

Dear Oscar,

I tried to investiage the additional test (reported at Drop-In) that is failing
on the heading-level parameter.

I copied the source file from the "interactive" example in the CLI test suite
and processed it with pretext/pretext. No error report for the heading-level.
I did not use a publication file, nor was the #interactive's JS available, and
of course, no project file. But those things all looked irrelevant. A bit stumped.

Before that, on suspicion, I tried a #section-less #article with a #p and a
#theorem. No BUG report issued.

Can you reproduce independent of the test suite?

Rob

>>>> MTAwMDAxMS5iZWV6ZXI.1779075135%40pnsh
>>>> .
>>>>
>>>
>>
>

[Oscar Levin]

Hi Rob,

I do not get the error if I try to build html.  It only shows up if I try to build a pdf, which requires generating assets.  So in particular, it seems to be coming from the `extract-interative.xsl` conversion.

Oscar.

To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/MTAwMDAxNy5iZWV6ZXI.1779230009%40pnsh.

[Rob Beezer]

OK, got it. Sorry I missed that during our discussion. Thanks.

[Rob Beezer]

Should be fixed now:

https://github.com/PreTeXtBook/pretext/pull/2866

Hopefully that gets CLI nightlies back on track!

Rob

[Oscar Levin]

Excellent.  Interestingly, the nightly deployed correctly over night (at 3am this morning).  In any event, it looks like we are back on track.

To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/MTAwMDA0MS5iZWV6ZXI.1779289387%40pnsh.

[Oscar Levin]

Here is another one I've stumbled on (although not an issue for the nightlies).  When building the webwork sample chapter, I got:

error: * PTX:BUG:     "hN" template reached without a $heading-level parameter on element <task> at pretext/book/chapter/section/exercise/webwork-reps/static/task; defaulting to h2

Comes from `pretext-html.xsl`.  There were a few that had doubly nested tasks too.