refactor(markdown): externalize headers and title plugin

BREAKING CHANGE: `markdown.extractHeaders` has been renamed to `markdown.headers` BREAKING CHANGE: `markdown.extractTitle` has been renamed to `markdown.title`
vuepress · Jul 2, 2022 · 8441569 · 8441569
1 parent 20f8a3f
commit 8441569
Show file tree

Hide file tree

Showing 24 changed files with 102 additions and 704 deletions.
diff --git a/docs/guide/migration.md b/docs/guide/migration.md
@@ -118,9 +118,7 @@ Use [extendsMarkdown](../reference/plugin-api.md#extendsmarkdown) hook.
 
 #### markdown.extractHeaders
 
-Changed.
-
-See [Config > markdown.extractHeaders](../reference/config.md#markdown-extractheaders)
+Moved to [markdown.headers](../reference/config.md#markdown-headers).
 
 #### Webpack Related Configs
 

diff --git a/docs/reference/config.md b/docs/reference/config.md
@@ -488,75 +488,19 @@ You should not configure it unless you understand what it is for.
 - Also see:
   - [Guide > Markdown > Syntax Extensions > Emoji](../guide/markdown.md#emoji)
 
-### markdown.extractHeaders
+### markdown.headers
 
-- Type: `ExtractHeadersPluginOptions | false`
+- Type: `HeadersPluginOptions | false`
 
 - Details:
 
-  Options for VuePress built-in markdown-it extract-headers plugin.
-
-  It will extract page headers to page data, which would be used for generating sidebar, table of contents, etc. For example, the sidebar of current page is auto generated from the headers that extracted by this plugin.
+  Options for [@mdit-vue/plugin-headers](https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-headers).
 
   Set to `false` to disable this plugin.
 
 - Also see:
   - [Node API > Page Properties > headers](./node-api.md#headers)
 
-#### markdown.extractHeaders.level
-
-- Type: `number[]`
-
-- Default: `[2, 3]`
-
-- Details:
-
-  Header levels that going to be extracted.
-
-  For example, if you set this option to `[2]`, only `##` headers will be extracted.
-
-  Should be a subset of [markdown.anchor.level](#markdown-anchor) option to ensure the extracted links are existed.
-
-#### markdown.extractHeaders.slugify
-
-- Type: `(str: string) => string`
-
-- Details:
-
-  A function to get the extracted slug of header from the raw header title.
-
-  Should use the same slugify function with [markdown.anchor.slugify](#markdown-anchor) to ensure the links are matched.
-
-::: tip
-If you really want to modify the slugify function, you'd better change the [markdown.slugify](#markdown-slugify) option instead of this one. Otherwise you have to set all the options about slugify function to ensure they are consistent.
-:::
-
-#### markdown.extractHeaders.format
-
-- Type: `((str: string) => string) | undefined`
-
-- Default: `undefined`
-
-- Details:
-
-  A function to format the extracted title of header from the raw header title.
-
-### markdown.extractTitle
-
-- Type: `undefined | false`
-
-- Details:
-
-  Options for VuePress built-in markdown-it extract-title plugin.
-
-  It will extract title to page data, which will be used as the page title.
-
-  Set to `false` to disable this plugin.
-
-::: danger
-You should not configure it unless you understand what it is for.
-:::
-
 ### markdown.importCode
 
 - Type: `ImportCodePluginOptions | false`
@@ -639,6 +583,20 @@ You should not configure it unless you understand what it is for.
 
   The default slugify function.
 
+### markdown.title
+
+- Type: `undefined | false`
+
+- Details:
+
+  Options for [@mdit-vue/plugin-title](https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-title).
+
+  Set to `false` to disable this plugin.
+
+::: danger
+You should not configure it unless you understand what it is for.
+:::
+
 ### markdown.toc
 
 - Type: `TocPluginOptions | false`

diff --git a/docs/reference/default-theme/config.md b/docs/reference/default-theme/config.md
@@ -415,9 +415,9 @@ module.exports = {
   - Set to `2` to include `<h2>` and `<h3>` headers.
   - ...
 
-  The max value depends on which levels of headers you have extracted via [markdown.extractHeaders.level](../config.md#markdown-extractheaders).
+  The max value depends on which levels of headers you have extracted via [markdown.headers.level](../config.md#markdown-headers).
 
-  The default value of `markdown.extractHeaders.level` is `[2, 3]`, so the default max value of `sidebarDepth` is `2`.
+  The default value of `markdown.headers.level` is `[2, 3]`, so the default max value of `sidebarDepth` is `2`.
 
   You can override this global option via [sidebarDepth](./frontmatter.md#sidebardepth) frontmatter in your pages.
 

diff --git a/docs/reference/node-api.md b/docs/reference/node-api.md
@@ -482,7 +482,7 @@ interface PageHeader {
   Headers of the page.
 
 - Also see:
-  - [Config > markdown.extractHeaders](./config.md#markdown-extractheaders)
+  - [Config > markdown.headers](./config.md#markdown-headers)
 
 ### data
 

diff --git a/docs/reference/plugin-api.md b/docs/reference/plugin-api.md
@@ -214,10 +214,10 @@ Modifying the default header levels that going to be extracted:
 ```js
 export default {
   extendsMarkdownOptions: (markdownOptions, app) => {
-    if (markdownOptions.extractHeaders === false) return
-    markdownOptions.extractHeaders ??= {}
-    if (markdownOptions.extractHeaders.level) return
-    markdownOptions.extractHeaders.level = [2, 3, 4, 5, 6]
+    if (markdownOptions.headers === false) return
+    markdownOptions.headers ??= {}
+    if (markdownOptions.headers.level) return
+    markdownOptions.headers.level = [2, 3, 4, 5, 6]
   },
 }
 ```

diff --git a/docs/zh/guide/migration.md b/docs/zh/guide/migration.md
@@ -118,9 +118,7 @@ VuePress v2 的核心思想和流程是和 v1 一致的，但 v2 API 经过了
 
 #### markdown.extractHeaders
 
-有修改。
-
-参考 [配置 > markdown.extractHeaders](../reference/config.md#markdown-extractheaders)
+移动至 [markdown.headers](../reference/config.md#markdown-headers) 。
 
 #### Webpack 相关配置
 

diff --git a/docs/zh/reference/config.md b/docs/zh/reference/config.md
@@ -487,68 +487,26 @@ VuePress 在开发和构建时会加载临时文件，因此临时文件目录
 - 参考：
   - [指南 > Markdown > 语法扩展 > Emoji](../guide/markdown.md#emoji)
 
-### markdown.extractHeaders
+### markdown.headers
 
-- 类型： `ExtractHeadersPluginOptions | false`
+- 类型： `HeadersPluginOptions | false`
 
 - 详情：
 
-  VuePress 内置的 markdown-it extract-headers 插件的配置项。
-
-  它将会把页面的子标题提取到 Page Data 中，可以用于生成侧边栏、目录等。比如当前页面的侧边栏，就是由这个插件提取出的标题来自动生成的。
+  [@mdit-vue/plugin-headers](https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-headers) 插件的配置项。
 
   设置为 `false` 可以禁用该插件。
 
 - 参考：
   - [Node API > Page 属性 > headers](./node-api.md#headers)
 
-#### markdown.extractHeaders.level
-
-- 类型： `number[]`
-
-- 默认值： `[2, 3]`
-
-- 详情：
-
-  需要提取的子标题层级。
-
-  举例来说，如果你把该选项设为 `[2]` ，那么只会提取 `##` 子标题。
-
-  它应该是 [markdown.anchor.level](#markdown-anchor) 选项的一个子集，以便确保提取出来的链接是存在的。
-
-#### markdown.extractHeaders.slugify
-
-- 类型： `(str: string) => string`
-
-- 详情：
-
-  一个函数，根据原始的子标题来获取提取出的子标题 slug 。
-
-  它应该使用和 [markdown.anchor.slugify](#markdown-anchor) 选项相同的 slugify 函数，来确保链接是匹配的。
-
-::: tip
-如果你确实想要修改 slugify 函数，建议你修改 [markdown.slugify](#markdown-slugify) 配置项，否则你必须同时修改其他的 slugify 函数配置来确保它们是一致的。
-:::
-
-#### markdown.extractHeaders.format
-
-- 类型： `((str: string) => string) | undefined`
-
-- 默认值： `undefined`
-
-- 详情：
-
-  一个函数，将原始的子标题格式化为提取出的标题。
-
-### markdown.extractTitle
+### markdown.title
 
 - 类型： `undefined | false`
 
 - 详情：
 
-  VuePress 内置的 markdown-it extract-title 插件的配置项。
-
-  它将会把大标题提取到 Page Data 中，将会被用作页面标题。
+  [@mdit-vue/plugin-title](https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-title) 插件的配置项。
 
   设置为 `false` 可以禁用该插件。
 

diff --git a/docs/zh/reference/default-theme/config.md b/docs/zh/reference/default-theme/config.md
@@ -415,9 +415,9 @@ module.exports = {
   - 设为 `2` 来包含 `<h2>` 和 `<h3>` 标题。
   - ...
 
-  最大值取决于你通过 [markdown.extractHeaders.level](../config.md#markdown-extractheaders) 提取了哪些级别的标题。
+  最大值取决于你通过 [markdown.headers.level](../config.md#markdown-headers) 提取了哪些级别的标题。
 
-  由于 `markdown.extractHeaders.level` 的默认值是 `[2, 3]` ，因此 `sidebarDepth` 的默认最大值是 `2` 。
+  由于 `markdown.headers.level` 的默认值是 `[2, 3]` ，因此 `sidebarDepth` 的默认最大值是 `2` 。
 
   你可以通过页面的 [sidebarDepth](./frontmatter.md#sidebardepth) frontmatter 来覆盖这个全局配置。
 

diff --git a/docs/zh/reference/node-api.md b/docs/zh/reference/node-api.md
@@ -480,7 +480,7 @@ interface PageHeader {
   该 Page 的小标题。
 
 - 参考：
-  - [配置 > markdown.extractHeaders](./config.md#markdown-extractheaders)
+  - [配置 > markdown.headers](./config.md#markdown-headers)
 
 ### data
 

diff --git a/docs/zh/reference/plugin-api.md b/docs/zh/reference/plugin-api.md
@@ -214,10 +214,10 @@ export default {
 ```js
 export default {
   extendsMarkdownOptions: (markdownOptions, app) => {
-    if (markdownOptions.extractHeaders === false) return
-    markdownOptions.extractHeaders ??= {}
-    if (markdownOptions.extractHeaders.level) return
-    markdownOptions.extractHeaders.level = [2, 3, 4, 5, 6]
+    if (markdownOptions.headers === false) return
+    markdownOptions.headers ??= {}
+    if (markdownOptions.headers.level) return
+    markdownOptions.headers.level = [2, 3, 4, 5, 6]
   },
 }
 ```

diff --git a/packages/@vuepress/core/__tests__/pluginApi/createHookQueue.spec.ts b/packages/@vuepress/core/__tests__/pluginApi/createHookQueue.spec.ts
@@ -107,7 +107,7 @@ describe('core > pluginApi > createHookQueue', () => {
         markdownOptions.emoji = false
       })
       const func2 = jest.fn((markdownOptions) => {
-        markdownOptions.extractHeaders = false
+        markdownOptions.headers = false
       })
       hook.add({
         pluginName: 'test1',
@@ -124,7 +124,7 @@ describe('core > pluginApi > createHookQueue', () => {
       expect(func1).toHaveBeenCalledWith(markdownOptions, app)
       expect(func2).toHaveBeenCalledTimes(1)
       expect(func2).toHaveBeenCalledWith(markdownOptions, app)
-      expect(markdownOptions).toEqual({ emoji: false, extractHeaders: false })
+      expect(markdownOptions).toEqual({ emoji: false, headers: false })
     })
 
     it(`extendsMarkdown`, async () => {

diff --git a/packages/@vuepress/core/src/page/renderPageContent.ts b/packages/@vuepress/core/src/page/renderPageContent.ts
@@ -52,6 +52,6 @@ export const renderPageContent = async ({
     headers,
     links,
     sfcBlocks,
-    title,
+    title: frontmatter.title ?? title,
   }
 }
diff --git a/packages/@vuepress/markdown/__tests__/markdown.spec.ts b/packages/@vuepress/markdown/__tests__/markdown.spec.ts
@@ -6,8 +6,6 @@ describe('@vuepress/markdown > markdown', () => {
 
     it.todo('emoji')
 
-    it.todo('extractHeaders')
-
     it.todo('links')
   })