Request support for heading offset

[xpe]

Would you be open to adding a configuration option to allow for offsetting of headings?

For example, adding an offset of 2 would map #-><h3> and ##-><h4> and so on.

Why

Hand-editing Markdown levels is often described as a workaround. However, this workaround fails if the same Markdown file gets included by different templates using different nesting levels for headers.

Related Work

For example, this has been implemented in at least one markdown processor; see BlackFriday (GoLang):

// HTMLRendererParameters is a collection of supplementary parameters tweaking
// the behavior of various parts of HTML renderer.
type HTMLRendererParameters struct {
	// ... <content snipped by xpe> ...      
	// Increase heading levels: if the offset is 1, <h1> becomes <h2> etc.
	// Negative offset is also valid.
	// Resulting levels are clipped between 1 and 6.
	HeadingLevelOffset int
}

[ollpu]

This can be done in a postprocessor (this one only does positive offsets, but you get the idea):

fn heading_offset<'a>(
    parser: impl Iterator<Item = Event<'a>>,
    offset: usize,
) -> impl Iterator<Item = Event<'a>> {
    parser.map(move |mut event| {
        match &mut event {
            Event::Start(Tag::Heading { level, .. }) | Event::End(TagEnd::Heading(level)) => {
                *level = (*level as usize + offset)
                    .try_into()
                    .unwrap_or(HeadingLevel::H6);
            }
            _ => {}
        }
        event
    })
}

I don't know if we want this in the main crate, but we could have a pulldown-cmark-contrib crate for things like this.