Heading levels

[eereeska]

Description

Please, add ability to control allowed heading levels such as CKEditor do

Example

It can be via config, similar to heading_permalink:

'heading_permalink' => [
    'min_heading_level' => 1,
    'max_heading_level' => 6,
],

To:

'headings' => [
    'min_level' => 2,
    'max_level' => 4,
],

So # H1 will became ## H2 & ###### H6 became #### H4 (closest allowed one)

Did this project help you today? Did it make you happy in any way?

Definitely love it ❤️

[eereeska]

bump

[samwilson]

Would this mean that e.g. with min_level=2 a heading with one asterisk # Head would be rendered as <h2>?

A use case that I often have is that a document with headings needs to be rendered both standalone (where it's headings would be as written) and also as subsections (where the headings would all be dropped down a level). Is that the sort of thing that this would accomplish?

[colinodell]

This suggestion makes sense to me.

I'd recommend we create a separate extension for it, perhaps called LimitHeadingsExtension or something similar. That extension could observe the DocumentParsedEvent and run some code to adjust the heading levels throughout the parsed AST.

Anyone interested in contributing this? 😉

[phpfui]

Looks line @eyupcanakman has implemented this in #1113

The bigger problem I feel is that the W3 HTML Validator is now reporting any gap between header sizes as an error. I feel it should be a warning, but that is not my decision to make. The errors on this page are all markdown files processed with this library. You can see the Guzzle README.md showing up second in the list. The problem is it starts with H1, then goes to H3. While this may look good typographically, it is an error according to W3.org.

I am not sure how to solve this problem. Apparently you can go up any number of levels, but only down one at a time. So you upgrade lower headers, or do you downgrade higher headers?

[eyupcanakman]

@phpfui Good point, but that's a separate issue.
This PR (#1113) is strictly about clamping min/max levels to fit markdown into existing site layouts. Fixing W3C heading gaps (jumping from H1 to H3) requires a completely different approach. Mixing both in one extension would make the parsing logic unpredictable.

W3C compliance would be better handled by a dedicated extension or a config like warn_on_w3_violations instead of forcing HTML changes here.

If we open a new issue for that specific feature, I can work on integrating it.

[phpfui]

@eyupcanakman agreed it is a separate issue. Just bringing up in an existing issue.

Should I start a new issue? Not sure I have the knowledge to contribute a PR. But there needs to be an agreement on the correct solution.

[eyupcanakman]

@phpfui yeah, opening a new issue is best.

Just to clarify. I'm a contributor here, not a core maintainer. Opening an issue will let the actual maintainers decide on the correct solution. Once they agree on an approach I'd be happy to write the PR for it

[samwilson]

The above PR works in my tests. Looks good.

I do wonder if it'd be good to shift headings, rather than just limiting the top/bottom limits. As it is, with 'min_heading_level' => 3 for example, a document with ## Foo\n\n### Bar ends up with <h3>Foo</h3><h3>Bar</h3>, but it feels like it'd be more expected for it to have all headings moved downwards and to output <h3>Foo</h3><h4>Bar</h4>. Would that be something that'd be worth doing? Perhaps as a separate config option (e.g. maybe just a heading-level mapping, so everything has to be made explicit; there's only seven levels after all).