rust-lang / rust-lang/mdBook

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

Open
#3,003 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.