It should be possible to create fenced divs with non-h3 headings

[tobyhodges]

Can we find a way to adjust the behaviour of sandpaper, to modify the heading level of fenced divs based on what is written in the source (R) Markdown?

At the moment, it appears that most fenced div headings are rendered as h3, except for the headings of solutions and hints, which are rendered as h4. The heading hierarchy of an episode can be disrupted by this, impacting the accessibility of the page.

Consider the following example:

## My section
This is some text introducing the section. The section includes two sub-sections.

### First sub-section
This is the first sub-section. It also has two subsections, but these are preceded by an exercise.
For the heading hierarchy of the page to make sense, this exercise should have an h4 heading to indicate that it belongs within the sub-section.

:::::: challenge

#### Exercise
What level with the heading be for this exercise?

::: solution

The exercise heading will be h3. The heading of this solution will be h4.

::::::::::::

::::::::::::::::


#### First sub-sub-section
Now we are writing under an h4 heading, so the exercise below should have an h5 heading.

:::::: challenge

##### Another Exercise
What level with the heading be for this exercise?

::: solution

The exercise heading will be h3. The heading of this solution will be h4.

::::::::::::

::::::::::::::::


#### Second sub-sub-section
Another h4 heading, which will now appear to belong 'under' the h3 of the exercise above.

Ideally, the resulting heading hierarchy of the content written above would be as follows (indentation added for illustration):

<h2>Section</h2>
    <h3>First sub-section</h3>
        <h4>Exercise</h4>
        <h4>First sub-sub-section</h4>
            <h5>Another exercise</h5>
        <h4>Second sub-sub-section</h4>

which makes it clear to which [sub-]sub-section the exercises belong. At the moment, this will be the structure of the rendered page:

<h2>Section</h2>
    <h3>First sub-section</h3>
    <h3>Exercise</h3>
        <h4>First sub-sub-section</h4>
    <h3>Another exercise</h3>
        <h4>Second sub-sub-section</h4>

[astroDimitrios]

As in your example the challenge block is currently forced to be h3.

To accurately determine what level to place the header at I think we need to store the level of the previous header as a global variable in the lua filter, otherwise when we pass over the challenge block I don't think there is a way to know what preceded it.

[ndporter]

I don't know it's necessarily bad to enforce a level of uniformity in the appearance of headers in callouts and other special blocks - it prevents relying on lesson developers and maintainers to follow best practices and I don't know that we typically need that fine-grained of control.

If we are going to allow variance, though, it would be ideal to have the variance take place relative to the enclosing structure, such that the document structure remains clean and accessible to screen readers, summarizers, and other technology. That is, the header level inside special blocks should be 1 level below that of the enclosing section (so typically h3 but sometimes h4, since h2s are primary headings in most lessons).

[astroDimitrios]

@ndporter we can always use css to overwrite any changes to fontsize, lowering the challenge header may have so there is no visual difference.

[brownsarahm]

If it's hard to implement automatically increment, I think honoring what is in the markdown makes maintenance easier than the current behavior which makes the rendered html inconsistent with the markdown(and confused me as a maintainer).

That also will make it so that markdown editors can create a correct outline structure for people while editing (increasing chances that we get good behavior in the rendered html without the auto-increment).

[froggleston]

Thanks for the question and discussion! I agree with @brownsarahm - automatic incrementing would be very difficult to implement cleanly, and quickly. For every section we would need to check the previous and following sections in order to "overwrite" the lesson developer's markdown with a forced Workbench structure. This would indeed make maintenance more difficult, and it would also be opaque to developers as to why their lesson structure might be changed with no warnings as to why.

I would rather improve the awareness of heading structure in our documentation.