Skip to content

Including non-existent regions includes entire file content #4625

Open
@BriceN

Description

@BriceN

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

  • Check if you're on the latest VitePress version.
    Follow our Code of Conduct
    Read the docs.
    Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @BriceN@brc-dd

        Issue actions

          Including non-existent regions includes entire file content · Issue #4625 · vuejs/vitepress