Description
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
- 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.
Expected behavior
When a region specified in an include statement doesn't exist in the target file, VitePress should either:
- Include nothing
- Have a configurable option for this behavior
System Info
System:
OS: Windows 11 10.0.22631
CPU: (16) x64 Intel(R) Core(TM) i7-6900K CPU @ 3.20GHz
Memory: 15.87 GB / 31.90 GB
Binaries:
Node: 18.18.2 - C:\Program Files\nodejs\node.EXE
Yarn: 1.22.21 - ~\AppData\Roaming\npm\yarn.CMD
npm: 9.8.1 - C:\Program Files\nodejs\npm.CMD
Browsers:
Edge: Chromium (128.0.2739.79)
Internet Explorer: 11.0.22621.3527
npmPackages:
vitepress: ^2.0.0-alpha.4 => 2.0.0-alpha.4
Additional context
To elaborate on mt specific usecase :
## Function Documentation
Generated title
<!-- @include: ./autodoc/slots/headers.md#my.function -->
Generated content
Generated content
Generated content
<!-- @include: ./autodoc/slots/descriptions.md#my.function -->
Generated content
Generated content
Generated content
<!-- @include: ./autodoc/slots/examples.md#my.function -->
<!-- @include: ./autodoc/slots/footers.md#my.function -->
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 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.
Validations
- Check if you're on the latest VitePress version.Follow our Code of ConductRead the docs.Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
Activity