You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
When using the markdown file inclusion feature with a VS Code region that doesn't exist, VitePress includes the entire file instead of including nothing. This can lead to unexpected content being included in documentation, especially when working with a modular documentation system where some regions may be intentionally missing for certain functions/components.
I'm using a modular documentation system with "slots" - where different parts of documentation for each function (headers, descriptions, examples, etc.) are stored in separate files. Each function's documentation components are tagged with regions matching the function name. This approach allows me to maintain clean separation of documentation components and update them independently. However, when a specific function doesn't have content for a particular slot (e.g., no examples), the current behavior causes the entire slot file to be included instead of nothing, severely breaking the documentation structure.
Reproduction
Create a main markdown file that includes a region from another file:
index.md:
# Example<!--@include: ./example.md#notexist-->
Create the included file with regions that don't match the requested one:
example.md:
<!-- #region test -->## inside region<!-- #endregion test -->## outside region
When building with VitePress, the output is:
# Example## inside region## outside region
Instead of including nothing, VitePress includes the entire file because the region #notexist is not found.
In this example, I'm generating documentation for API functions where:
headers.md contains all function header content in separate regions
descriptions.md contains all detailed descriptions
examples.md contains code examples
footers.md contains additional notes and related functions
Not every function has content in every slot file (some might lack examples or footers). With the current behavior, if a function doesn't have an example region defined in examples.md, the entire examples file gets included - showing examples for completely unrelated functions, creating massively incorrect and confusing documentation. The same happens with any other missing region.
Describe the bug
When using the markdown file inclusion feature with a VS Code region that doesn't exist, VitePress includes the entire file instead of including nothing. This can lead to unexpected content being included in documentation, especially when working with a modular documentation system where some regions may be intentionally missing for certain functions/components.
I'm using a modular documentation system with "slots" - where different parts of documentation for each function (headers, descriptions, examples, etc.) are stored in separate files. Each function's documentation components are tagged with regions matching the function name. This approach allows me to maintain clean separation of documentation components and update them independently. However, when a specific function doesn't have content for a particular slot (e.g., no examples), the current behavior causes the entire slot file to be included instead of nothing, severely breaking the documentation structure.
Reproduction
index.md:
example.md:
Instead of including nothing, VitePress includes the entire file because the region
#notexist
is not found.StackBlitz reproduction
Expected behavior
When a region specified in an include statement doesn't exist in the target file, VitePress should either:
System Info
Additional context
To elaborate on mt specific usecase :
In this example, I'm generating documentation for API functions where:
headers.md
contains all function header content in separate regionsdescriptions.md
contains all detailed descriptionsexamples.md
contains code examplesfooters.md
contains additional notes and related functionsNot every function has content in every slot file (some might lack examples or footers). With the current behavior, if a function doesn't have an example region defined in
examples.md
, the entire examples file gets included - showing examples for completely unrelated functions, creating massively incorrect and confusing documentation. The same happens with any other missing region.Validations
The text was updated successfully, but these errors were encountered: