Skip to content

Including non-existent regions includes entire file content #4625

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
4 tasks done
BriceN opened this issue Mar 17, 2025 · 0 comments
Open
4 tasks done

Including non-existent regions includes entire file content #4625

BriceN opened this issue Mar 17, 2025 · 0 comments

Comments

@BriceN
Copy link

BriceN commented Mar 17, 2025

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

  1. Create a main markdown file that includes a region from another file:

index.md:

# Example

<!--@include: ./example.md#notexist-->
  1. Create the included file with regions that don't match the requested one:

example.md:

<!-- #region test -->

## inside region

<!-- #endregion test -->

## outside region
  1. 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.

StackBlitz reproduction

Expected behavior

When a region specified in an include statement doesn't exist in the target file, VitePress should either:

  1. Include nothing
  2. 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:

  1. headers.md contains all function header content in separate regions
  2. descriptions.md contains all detailed descriptions
  3. examples.md contains code examples
  4. 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.

Validations

@BriceN BriceN added the bug: pending triage Maybe a bug, waiting for confirmation label Mar 17, 2025
@brc-dd brc-dd added needs more discussion and removed bug: pending triage Maybe a bug, waiting for confirmation labels Mar 18, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants