Skip to content

fix(md)!: change behavior of regions in snippets - #5014

Open
its-miroma wants to merge 11 commits into
vuejs:mainfrom
its-miroma:regions
Open

fix(md)!: change behavior of regions in snippets#5014
its-miroma wants to merge 11 commits into
vuejs:mainfrom
its-miroma:regions

Conversation

@its-miroma

@its-miroma its-miroma commented Nov 3, 2025 •
edited
Loading

Copy link
Copy Markdown
Contributor

Description

  • include all regions with the same name, not just the first one
  • when a file does not contain the region, don't include it entirely, rather warn that the region was not found
  • add option to strip all #region comments from the included snippet
  • support pure JSON files, by allowing regions to be declared in the keys

Rationale

VitePress supports including a part of a file through a VS Code region. However, when multiple regions have the same name, only one is included.

The workaround plugin suggested in #3690 is no longer maintained. 1 Furthermore, it suffers from a memory leak causing huge RAM usage. 2
While we at Fabric Docs have forked the plugin 3 to fix some issues, it still feels fragile.
Another problem is having to use two different syntaxes (<<< vs @[]()) for doing the same thing, causing confusion.

Since this feature has been requested by VitePress directly, I don't think there's any point in working on the plugin any further.

Linked Issues

fix #3690
fix #4625

Additional Context

Footnotes

  1. https://github.com/fabioaanthony/markdown-it-vuepress-code-snippet-enhanced/issues/7 ↩

  2. https://discord.com/channels/507304429255393322/1208846408552030238/1407245292482330695 via https://discord.fabricmc.net/ ↩

  3. https://github.com/IMB11/md-it-enhanced-snippets ↩

@its-miroma

This comment was marked as resolved.

Sign in to view
@its-miroma

This comment was marked as outdated.

Sign in to view
@pkg-pr-new

pkg-pr-new Bot commented Nov 6, 2025 •
edited
Loading

Copy link
Copy Markdown 
npm i https://pkg.pr.new/vitepress@5014

commit: 6c9bf5c

@its-miroma its-miroma changed the title feat(markdown): include all regions with same name feat(md)!: include all regions with same name Dec 21, 2025
@its-miroma its-miroma changed the title feat(md)!: include all regions with same name fix(md)!: include all regions with same name Dec 21, 2025
@its-miroma its-miroma changed the title fix(md)!: include all regions with same name fix(md)!: change behavior of regions in snippets Dec 21, 2025
@its-miroma

its-miroma commented Dec 21, 2025 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

I hope this PR can get some reviews.

I'd also want to make the following breaking changes, but possibly for another PR:

  • deprecate @include, replaced with <<< which would not create a code block for Markdown files
  • to import a Markdown file in a code block, put <<< in a code block
  • somehow add support for multiple line ranges in the <<< syntax, without conflicting with highlighting

@its-miroma
its-miroma force-pushed the regions branch 2 times, most recently from 0e2e16a to c19b76a Compare December 22, 2025 21:05
@its-miroma
its-miroma force-pushed the regions branch 2 times, most recently from 317f38b to 2d0695b Compare January 27, 2026 14:01
@brc-dd
brc-dd self-requested a review January 31, 2026 18:16
@brc-dd brc-dd self-assigned this Feb 5, 2026
its-miroma
its-miroma commented Feb 12, 2026
View reviewed changes
Comment thread src/node/markdown/plugins/snippet.ts Outdated
@its-miroma its-miroma mentioned this pull request Mar 15, 2026
Merged
its-miroma added a commit to its-miroma/fmc that referenced this pull request Mar 16, 2026
@its-miroma
apply vuejs/vitepress#5014
db9b539
@its-miroma its-miroma mentioned this pull request Mar 16, 2026
Merged
its-miroma added a commit to its-miroma/fmc that referenced this pull request Mar 16, 2026
@its-miroma
apply vuejs/vitepress#5014
53015ae
its-miroma added a commit to its-miroma/fmc that referenced this pull request Mar 16, 2026
@its-miroma
apply vuejs/vitepress#5014
7de5199
its-miroma added a commit to its-miroma/fmc that referenced this pull request Mar 16, 2026
@its-miroma
apply vuejs/vitepress#5014
4f93e09
its-miroma added a commit to its-miroma/fmc that referenced this pull request Mar 22, 2026
@its-miroma
feat: apply vuejs/vitepress#5014
e7fc438
its-miroma added a commit to its-miroma/fmc that referenced this pull request Mar 22, 2026
@its-miroma
feat: apply vuejs/vitepress#5014
2e113b7
its-miroma added a commit to its-miroma/fmc that referenced this pull request Mar 22, 2026
@its-miroma
feat: apply vuejs/vitepress#5014
cc19a20
its-miroma added a commit to its-miroma/fmc that referenced this pull request Mar 22, 2026
@its-miroma
feat: apply vuejs/vitepress#5014
0a6efc9
its-miroma added a commit to its-miroma/fmc that referenced this pull request Mar 22, 2026
@its-miroma
feat: apply vuejs/vitepress#5014
a646b3f
its-miroma added a commit to its-miroma/fmc that referenced this pull request Mar 23, 2026
@its-miroma
Merge branch 'migration' (early part) into all
f8dc3f3 
* 'migration' (early part):
  apply some manual fixes
  the migration script
  drop mention of transclusions
  fix: transclusions from FabricMC#415
  feat: apply vuejs/vitepress#5014
  chore: set minimumReleaseAge to 3 days
  chore: migrate to pnpm
its-miroma added a commit to its-miroma/fmc that referenced this pull request Mar 24, 2026
@its-miroma
feat: apply vuejs/vitepress#5014
f95710b
its-miroma added a commit to FabricMC/fabric-docs that referenced this pull request Mar 25, 2026
@its-miroma
fix: apply vuejs/vitepress#5014 (#529)
8848be5 
* chore: migrate to pnpm

* chore: set minimumReleaseAge to 3 days

* feat: apply vuejs/vitepress#5014

* fix: transclusions from #415
@brc-dd
brc-dd force-pushed the main branch 3 times, most recently from 15a0278 to 09af6c7 Compare March 26, 2026 04:26
its-miroma
its-miroma commented Mar 29, 2026
View reviewed changes
Comment thread src/node/markdown/markdown.ts Outdated
* Remove all #region markers when including snippets
* @default false
*/
stripMarkersFromSnippets?: boolean

@its-miroma its-miroma Mar 29, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe I should add a configurable mutateSnippet(regions: string[], context: ...) function, that will be run for every snippet. Some use cases:

  • Stripping imports from all snippets
  • Replacing comments with translated versions
  • Adding // ::: at region cuts
  • Adding a comment at the top with the full file path

@github-actions github-actions Bot added the stale label Jun 27, 2026
@its-miroma its-miroma mentioned this pull request Jul 15, 2026
Draft
@its-miroma

This comment was marked as resolved.

Sign in to view
@its-miroma
its-miroma force-pushed the regions branch 5 times, most recently from a04f385 to 5082cdc Compare July 25, 2026 12:53
its-miroma added 11 commits July 27, 2026 19:17
@its-miroma
refactor: simplify frontmatter stripping logic
26c55ef
@its-miroma
fix!: include all regions with the same name
bbeaa9b 
VitePress supports including a part of a file through a VS Code region.
However, when multiple regions have the same name, only one is included.

The workaround plugin suggested in vuejs#3690 is no longer maintained. [^1]
Furthermore, it suffers from a memory leak causing huge RAM usage. [^2]
While we at Fabric Docs have forked the plugin [^3] to fix some issues,
it still feels fragile. Another problem is having to use two different
syntaxes (`<<<` vs `@[]()`) for doing the same thing, causing confusion.

Since this feature has been requested by VitePress directly, I don't
think there's any point in working on the plugin any further.

fix vuejs#3690

[^1]: <fabioaanthony/markdown-it-vuepress-code-snippet-enhanced#7>
[^2]: <https://discord.com/channels/507304429255393322/1208846408552030238/1407245292482330695> via <https://discord.fabricmc.net/>
[^3]: <https://github.com/IMB11/md-it-enhanced-snippets>
@its-miroma
fix!: warn if region not found
29405f5 
when a region is not in the source file, instead
of including the whole file, warn that the #region
was not found in it.

fix vuejs#4625
@its-miroma
feat: optionally strip #region markers
dab70a7 
if `stripMarkersFromSnippets` is set, `<<<`
snippets will strip out all region markers:

```file.ts
// #region A
// #region B
console.log("Hello, World!");
// #endregion
// #endregion
```

<<< file.ts#A

...would not include "#region B" anymore
@its-miroma
feat: support regions in pure JSON
0b7a1ee
@its-miroma
feat: support different markers in same snippet
7a9e146
@its-miroma
fix!: comment markers
88117cf 
- require # before region, just like vscode
- do not accept `# #region`, just like vscode
- support case-insensitive REM comment
- require space after REM
@its-miroma
fix: support files with an extension only
204115d 
in `.gitignore`, `gitignore` is now detected as the extension
@its-miroma
refactor: extract and test stripMarkers
62d5b83 
change signature of dedent too, to avoid splitting and joining
@its-miroma
refactor!: treat all region markers as equivalent
6a483f0 
with this refactor, findRegions now iterates over each line only once,
and checks all markers to find the first satisfied.

For example, #a on:
```ts
// #region a
const a = 1
/* #region a */
const b = 2
// #endregion a
const c = 3
/* #endregion a */
```

...which would previously be rendered (assuming stripMarkers):
```ts
const a = 1
const b = 2
const b = 2
const c = 3
```

...is now correctly rendered:
```ts
const a = 1
const b = 2
const c = 3
```

BREAKING CHANGE: previously, the code stripped matching nested comments,
even when stripMarkersFromSnippets was false.

For example, #a on:
```ts
// #region a
const a = 1
// #region a
const b = 2
// #endregion a
const c = 3
// #region b
const d = 4
// #endregion b
const e = 5
// #endregion a
```

...which would previously be rendered (assuming !stripMarkers):
```ts
const a = 1
const b = 2
const c = 3
// #region b
const d = 4
// #endregion b
const e = 5
```

...is now rendered:
```ts
const a = 1
// #region a
const b = 2
// #endregion a
const c = 3
// #region b
const d = 4
// #endregion b
const e = 5
```
@its-miroma
fix!: strip frontmatter before locating regions
6c9bf5c 
previously, the frontmatter was not stripped prior to finding regions in
processIncludes. if a region was found in the frontmatter, the included
snippet would break in rendering.

For example, #a on:
```md
---
#region a
# this comment becomes a heading
#endregion a
---

Hello, World!

<!-- #region a -->
Some content
<!-- #endregion a -->
```

...which would previously be rendered:
```md
# this comment becomes a heading
Some content
```

...is now rendered as:
```md
Some content
```

other improvements:
- split and join `content` into `lines` only once
- place # outside capturing group in regionRE, to avoid a slice(1)
- call matter() only once, at the beginning. see comment in source
- avoid `as any` cast by using Infinity instead of undefined as end
- anchor #region at $ - ranges on regions still work: #region{1,3}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@brc-dd brc-dd Awaiting requested review from brc-dd

Assignees

@brc-dd brc-dd

Labels

cr-tracked stale

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Including non-existent regions includes entire file content Multi region snippet support

3 participants

@its-miroma @vue-bot @brc-dd