Feature Request: Support heading level offsets in {{#include}} directive

[Orefa]

Currently, when using the {{#include file.md}} directive, mdBook performs a literal string insertion of the target file. If the included file contains Markdown headings (e.g., starting with #), they retain their original level regardless of where they are included in the parent document.

This often results in a broken document hierarchy. For example, if a parent file has an # Introduction and includes a sub-file that also starts with # Sub-topic, the rendered output has two top-level H1 tags, which is semantically incorrect and visually inconsistent.

Proposed Feature

I propose adding an optional argument to the include directive to shift/offset heading levels.

Suggested Syntax:
{{#include file.md:level+=N}} or {{#include file.md:offset=N}}

Example Usage

If sub_file.md contains:

# My Section
## Subsection

In the parent main.md:

# Project Documentation

{{#include sub_file.md:level+=1}}

Expected Rendered Output:

# Project Documentation

## My Section
### Subsection

Alternatives Considered

• Manual adjustment: Manually changing headings in sub-files, which makes them look incorrect when viewed in isolation (e.g., starting a file with ####).
• External Preprocessors: Using a custom preprocessor to regex-replace # characters, but this is a common enough use case that it warrants a native implementation.

Additional Context

This feature would greatly improve the modularity of large books, allowing chapters to be composed of smaller, valid Markdown files that can still stand alone or be reused in different nesting depths.

---