Snippet headings adjustment

[nbanyan]

Description

Add an option to adjust the snippet to fit under the headings level of where it is inserted, similar to how the indentation is adjusted.

I currently use both Snippets and markdown_include.include in my MkDocs. Snippets are critical for maintaining the mechanical structure of a page (inserting another page's contents into a bulleted list) due to it adjusting indentation. include has an option inheritHeadingDepth that is useful for maintaining the organizational structure of a page by adjusting the heading levels, but it doesn't touch indentation.

Benefits

This would help preserve the visual and navigation tree structure of a page's headings and Table of Contents.

Solution Idea

Example:

include.md

## Title
Content text.
### Heading
Content text.

page.md

## Title
1. Text
    --8<-- "include.md"

Processed page.md

## Title
1. Text
    ### Title
    Content text.
    #### Heading
    Content text.

When adjusting headers, include adds extra # characters to the headings without further testing, which can easily run into \

text that start with #. Potential options for handling heading level overflow:

1. List with emphasis.

   Headings pushed into h7 or above are restructured to unordered (or ordered?) lists with bold text for the heading and the content indented appropriately.

   # Adjusted snippet

   ###### Title
   ####### Heading
   Content text.
   ######## Sub-Heading
   Content text.

   List conversion

   ###### Title
   * **Heading**
       Content text.
       * **Sub-Heading**
           Content text.

2. Heading limit cap.

   Simply truncate headings to h6. This looses some organizational structure of the inserted content, but requires minimal processing.

[facelessuser]

Please search issues before creating new issues, this is a duplicate of #1052. If you have ideas or additional comments to add to the discussion, please include them there.

[nbanyan]

I did a search for "Snippets" and somehow didn't see that one in the results. Any estimate on when this idea will be revisited?

[facelessuser]

I don't know, it isn't a straightforward problem. Header handling and snippet handling are two separate things. They have no knowledge of each other. Snippets performs a preprocessor pass before any Markdown parsing takes place, so headers added by snippets are unknown. Snippets doesn't parse the content, so it is unaware of where headers are. So then you must implement some syntax to specifically make snippet headers known when doing normal Markdown parsing. How do you know the intention of when a header should be incremented or decremented? I feel like there should be some sort of additional logic to specify the intention of header relations.

I am doubtful that inferring the user intention and automatically making headers relative is sufficient. I feel like this would be problematic without requiring some relative input guidance from the user.

Currently, I haven't yet re-visited this and I don't know specifically when I will.