Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#3,003 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 2 días

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
rust
Área
documentation

Línea de trabajo

Comienza con el comportamiento de la directiva {{#include}} descrito en el issue y compara las sintaxis propuestas level+=N y offset=N. Define cómo deben aplicarse los desplazamientos de encabezados al Markdown incluido y qué debe ocurrir en los límites de los niveles de encabezado. Se considera completado cuando un archivo incluido se renderiza con la jerarquía de encabezados desplazada solicitada y sigue siendo válido al utilizarse con distintas profundidades de anidamiento.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
Rust
Estrellas
22.2k
Forks
1.9k
Merge medio
3 d 11 h
PR fusionados (30 d)
5

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de rust-lang/mdBook

Todos los issues de rust-lang/mdBook

Issues similares

Más issues de Rust

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.