feat: markdown file inclusion support specify title

[btea]

Description

Linked Issues

close #4375

Additional Context

---

Tip

The author of this PR can publish a preview release by commenting /publish below.

[btea]

Could you please help review this PR? Thanks! @brc-dd

[brc-dd]

It's bit tricky than that.

• Need to handle nesting.
• Also, what should be done when same title is there many times?
• /[^#]/g matches ^ or #, you probably meant to write /^#+/

[btea]

• Need to handle nesting.
• Also, what should be done when same title is there many times?

Indeed, I thought too simply.

• /[^#]/g matches ^ or #, you probably meant to write /^#+/

I reviewed it and there is no mistake here.

/[^#]/gmatches all characters except #. I intentionally remove all characters here to get the length of the title # and find the end of the content under the matching title.

[brc-dd]

Ah right, sorry. So, you're essentially counting number of # in a heading? But this will give prefix length for # hi # there = 2. Might be better to do str.match(/^#+/)?.[0]?.length

[btea]

Yeah, you wrote it is better for the situation you mentioned. 👍

[btea]

• Need to handle nesting.

The interior looks to have handled the situation.

vitepress/src/node/utils/processIncludes.ts

Line 63 in d1f2afd

return processIncludes(srcDir, content, includePath, includes)

• Also, what should be done when same title is there many times?

Generally speaking, a page should not have multiple identical titles. If this is the case, perhaps we can keep the current logic and give a warning message.

[brc-dd]

@btea Can you review the implementation in #4608? The main change is it using heading ids (the one you see in url fragments) instead of whole title.

It solves various cases where there are things like badges or markdown syntax in headings, or even duplicate heading (markdown-it-anchor internally adds -{counter} to repeated headings. I think repeated subheadings (inside separate parent headings) are quite common). It also prevents false positives like headings inside code blocks, etc. Though that's quite uncommon.

The md.parse step might add some performance overhead but I think markdown-it's parser is quite fast and the difference will be in order of few milliseconds, which is tolerable for the features it provides.