expose a configurable outline config in frontmatter

[fi3ework]

Is your feature request related to a problem? Please describe.

For now, the outline config in frontmatter is not documented, however, the code is in the codebase. Just add outline: 'deep' to the page frontmatter and the outline can show 2 levels at most. So I think:

1. configuration of page outline of frontmatter should be documented.
2. The outline now only has one available type 'deep', but I think we should expose a more configurable config, such as ['h1', 'h2'] and an another deep type which equals to ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'] for short.
3. I found that page.headers is resolved from https://github.com/vuejs/vitepress/blob/22006e8d6e3ed45841979d684eb6a4ef999bd707/src/node/markdown/plugins/headings.ts#L6-L23 I think we can set the default value of headingPlugin to ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'] which means markdown-it will parse all headings in node side. And the outline configuration will only control which headings to render in the outline.

Describe the solution you'd like

The configuration of the outline will be like

Type: ('h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6')[] | 'deep'
Default: ['h2', 'h3']

also, we need to fix the code which only can handle [2, 3] level for now.

Describe alternatives you've considered

I believe parsing all headings will not cause a performance issue because markdown-it will try to iterate over all blocks (only a guess).

Additional context

I would like to implement this feature.

Validations

• [X] Follow our Code of Conduct
• [X] Read the docs.
• [X] Read the Contributing Guidelines.
• [X] Check that there isn't already an issue that asks for the same feature to avoid creating a duplicate.

[imjuniper]

Would it be possible to also add it as an app config? If I want to have a 2-level deep outline in all my files, I could add it there rather than in every file's frontmatter.

[fi3ework]

Would it be possible to also add it as an app config? If I want to have a 2-level deep outline in all my files, I could add it there rather than in every file's frontmatter.

implemented in #965

[imjuniper]

Oh cool! I assume it will be in the next release? (Soon? 😄)

[yzqzy]

That makes two of us 😄