Feature Request: Support heading level offsets in {{#include}} directive
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 22.2k
- Forks
- 1.9k
- PR merge metrics
- PR metrics pending
Description
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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the {{#include}} directive behavior described in the issue and compare the proposed level+=N and offset=N syntaxes. Define how heading offsets should apply to the included Markdown and what should happen at heading-level boundaries. Done means an included file renders with the requested shifted heading hierarchy while remaining valid when used at different nesting depths.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100