From cab5b8318e8143e1fe14e334a831cc7dbfdb5a73 Mon Sep 17 00:00:00 2001
From: Shigma <33423008+Shigma@users.noreply.github.com>
Date: Sun, 12 May 2019 23:00:48 +0800
Subject: [PATCH] refactor($theme-default): leverage
markdown-it-table-of-contents (#1436)
---
packages/@vuepress/core/lib/client/app.js | 3 -
.../core/lib/client/components/HeaderList.vue | 20 -----
.../core/lib/client/components/TOC.vue | 57 -------------
packages/@vuepress/markdown/index.js | 6 --
.../@vuepress/markdown/lib/tableOfContents.js | 83 -------------------
packages/@vuepress/theme-default/index.js | 13 ++-
packages/@vuepress/theme-default/package.json | 1 +
packages/docs/docs/config/README.md | 15 ----
packages/docs/docs/guide/markdown.md | 12 +--
packages/docs/docs/guide/using-vue.md | 22 -----
.../docs/docs/theme/default-theme-config.md | 20 +++++
packages/docs/docs/zh/config/README.md | 15 ----
packages/docs/docs/zh/guide/markdown.md | 12 +--
packages/docs/docs/zh/guide/using-vue.md | 22 -----
.../docs/zh/theme/default-theme-config.md | 20 +++++
yarn.lock | 5 ++
16 files changed, 65 insertions(+), 261 deletions(-)
delete mode 100644 packages/@vuepress/core/lib/client/components/HeaderList.vue
delete mode 100644 packages/@vuepress/core/lib/client/components/TOC.vue
delete mode 100644 packages/@vuepress/markdown/lib/tableOfContents.js
diff --git a/packages/@vuepress/core/lib/client/app.js b/packages/@vuepress/core/lib/client/app.js
index b29717a9..25b964c4 100644
--- a/packages/@vuepress/core/lib/client/app.js
+++ b/packages/@vuepress/core/lib/client/app.js
@@ -16,7 +16,6 @@ import Content from './components/Content.js'
import ContentSlotsDistributor from './components/ContentSlotsDistributor'
import OutboundLink from './components/OutboundLink.vue'
import ClientOnly from './components/ClientOnly'
-import TOC from './components/TOC.vue'
// suggest dev server restart on base change
if (module.hot) {
@@ -47,8 +46,6 @@ Vue.component('ClientOnly', ClientOnly)
// core components
Vue.component('Layout', getLayoutAsyncComponent('Layout'))
Vue.component('NotFound', getLayoutAsyncComponent('NotFound'))
-// markdown components
-Vue.component('TOC', TOC)
// global helper for adding base path to absolute urls
Vue.prototype.$withBase = function (path) {
diff --git a/packages/@vuepress/core/lib/client/components/HeaderList.vue b/packages/@vuepress/core/lib/client/components/HeaderList.vue
deleted file mode 100644
index a1945e08..00000000
--- a/packages/@vuepress/core/lib/client/components/HeaderList.vue
+++ /dev/null
@@ -1,20 +0,0 @@
-
-
-
-
-
-
-
-
-
-
diff --git a/packages/@vuepress/core/lib/client/components/TOC.vue b/packages/@vuepress/core/lib/client/components/TOC.vue
deleted file mode 100644
index 697e68c1..00000000
--- a/packages/@vuepress/core/lib/client/components/TOC.vue
+++ /dev/null
@@ -1,57 +0,0 @@
-
-
-
-
-
-
-
-
-
diff --git a/packages/@vuepress/markdown/index.js b/packages/@vuepress/markdown/index.js
index f3b4a38c..9fbed6d4 100644
--- a/packages/@vuepress/markdown/index.js
+++ b/packages/@vuepress/markdown/index.js
@@ -15,7 +15,6 @@ const componentPlugin = require('./lib/component')
const hoistScriptStylePlugin = require('./lib/hoist')
const convertRouterLinkPlugin = require('./lib/link')
const snippetPlugin = require('./lib/snippet')
-const tocPlugin = require('./lib/tableOfContents')
const emojiPlugin = require('markdown-it-emoji')
const anchorPlugin = require('markdown-it-anchor')
const {
@@ -32,7 +31,6 @@ module.exports = (markdown = {}) => {
const {
externalLinks,
anchor,
- toc,
plugins,
lineNumbers,
beforeInstantiate,
@@ -93,10 +91,6 @@ module.exports = (markdown = {}) => {
}, anchor)])
.end()
- .plugin(PLUGINS.TOC)
- .use(tocPlugin, [toc])
- .end()
-
if (lineNumbers) {
config
.plugin(PLUGINS.LINE_NUMBERS)
diff --git a/packages/@vuepress/markdown/lib/tableOfContents.js b/packages/@vuepress/markdown/lib/tableOfContents.js
deleted file mode 100644
index 5e32161e..00000000
--- a/packages/@vuepress/markdown/lib/tableOfContents.js
+++ /dev/null
@@ -1,83 +0,0 @@
-// reference: https://github.com/Oktavilla/markdown-it-table-of-contents
-
-const defaults = {
- includeLevel: [2, 3],
- containerClass: 'table-of-contents',
- markerPattern: /^\[\[toc\]\]/im,
- listType: 'ul',
- containerHeaderHtml: '',
- containerFooterHtml: ''
-}
-
-module.exports = (md, options) => {
- options = Object.assign({}, defaults, options)
- const tocRegexp = options.markerPattern
-
- function toc (state, silent) {
- var token
- var match
-
- // Reject if the token does not start with [
- if (state.src.charCodeAt(state.pos) !== 0x5B /* [ */) {
- return false
- }
- // Don't run any pairs in validation mode
- if (silent) {
- return false
- }
-
- // Detect TOC markdown
- match = tocRegexp.exec(state.src)
- match = !match ? [] : match.filter(function (m) { return m })
- if (match.length < 1) {
- return false
- }
-
- // Build content
- token = state.push('toc_open', 'toc', 1)
- token.markup = '[[toc]]'
- token = state.push('toc_body', '', 0)
- token = state.push('toc_close', 'toc', -1)
-
- // Update pos so the parser can continue
- var newline = state.src.indexOf('\n')
- if (newline !== -1) {
- state.pos = state.pos + newline
- } else {
- state.pos = state.pos + state.posMax + 1
- }
-
- return true
- }
-
- md.renderer.rules.toc_open = function () {
- return vBindEscape``
- }
-
- md.renderer.rules.toc_body = function () {
- return `${options.containerHeaderHtml}`
- + `${options.containerFooterHtml}`
- }
-
- md.renderer.rules.toc_close = function () {
- return ``
- }
-
- // Insert TOC
- md.inline.ruler.after('emphasis', 'toc', toc)
-}
-
-/** escape double quotes in v-bind derivatives */
-function vBindEscape (strs, ...args) {
- return strs.reduce((prev, curr, index) => {
- return prev + curr + (index >= args.length
- ? ''
- : `"${JSON.stringify(args[index])
- .replace(/"/g, "'")
- .replace(/([^\\])(\\\\)*\\'/g, (_, char) => char + '\\u0022')}"`)
- }, '')
-}
diff --git a/packages/@vuepress/theme-default/index.js b/packages/@vuepress/theme-default/index.js
index 01de7b12..29e79968 100644
--- a/packages/@vuepress/theme-default/index.js
+++ b/packages/@vuepress/theme-default/index.js
@@ -17,10 +17,19 @@ module.exports = (options, ctx) => ({
}
},
+ extendMarkdown (md) {
+ if (options.toc !== false) {
+ md.use(require('markdown-it-table-of-contents'), {
+ includeLevel: [2, 3],
+ ...options.toc
+ })
+ }
+ },
+
plugins: [
['@vuepress/active-header-links', options.activeHeaderLinks],
- '@vuepress/search',
- '@vuepress/plugin-nprogress',
+ ['@vuepress/search'],
+ ['@vuepress/nprogress'],
['container', {
type: 'tip',
defaultTitle: {
diff --git a/packages/@vuepress/theme-default/package.json b/packages/@vuepress/theme-default/package.json
index 192634b9..a8317610 100644
--- a/packages/@vuepress/theme-default/package.json
+++ b/packages/@vuepress/theme-default/package.json
@@ -34,6 +34,7 @@
"@vuepress/plugin-nprogress": "^1.0.0-alpha.47",
"@vuepress/plugin-search": "^1.0.0-alpha.47",
"docsearch.js": "^2.5.2",
+ "markdown-it-table-of-contents": "^0.4.3",
"stylus": "^0.54.5",
"stylus-loader": "^3.0.2",
"vuepress-plugin-container": "^2.0.0"
diff --git a/packages/docs/docs/config/README.md b/packages/docs/docs/config/README.md
index 5a0a7c6d..acd9ce2d 100644
--- a/packages/docs/docs/config/README.md
+++ b/packages/docs/docs/config/README.md
@@ -215,21 +215,6 @@ Options for [markdown-it-anchor](https://github.com/valeriangalliat/markdown-it-
The key and value pair will be added to `` tags that point to an external link. The default option will open external links in a new window.
-### markdown.toc
-
-- Type: `Object`
-
-This attribute will control the behaviour of `[[TOC]]`. It contains the following options:
-
-- includeLevel: [number, number], level of headers to be included, defaults to `[2, 3]`.
-- containerClass: string, the class name for the container, defaults to `table-of-contents`.
-- markerPattern: RegExp, the regular expression for the marker to be replaced with TOC, defaults to `/^\[\[toc\]\]/im`.
-- listType: string or Array, labels for all levels of the list, defaults to `"ul"`.
-- containerHeaderHtml: string, an HTML string for container header, defaults to `""`.
-- containerFooterHtml: string, an HTML string for container footer, defaults to `""`.
-
-We also provide a [global component TOC](../guide/using-vue.md#toc) which allows for more free control by passing props directly to ``.
-
### markdown.plugins
You can install any markdown-it plugins through `markdown.plugins` option. It is similar with [using VuePress plugins](../plugin/using-a-plugin.html#using-a-plugin). You can either use Babel style or object style. The `markdown-it-` prefix is optional and can omit in the list.
diff --git a/packages/docs/docs/guide/markdown.md b/packages/docs/docs/guide/markdown.md
index 6a32f0d1..c7c3f369 100644
--- a/packages/docs/docs/guide/markdown.md
+++ b/packages/docs/docs/guide/markdown.md
@@ -101,7 +101,7 @@ For more details, check out the [Front Matter](./frontmatter.md) page.
A list of all emojis available can be found [here](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.json).
-## Table of Contents
+## Table of Contents
**Input**
@@ -109,17 +109,13 @@ A list of all emojis available can be found [here](https://github.com/markdown-i
[[toc]]
```
-or
-
-```md
-
-```
-
**Output**
[[toc]]
-Rendering of TOC can be configured using the [`markdown.toc`](../config/README.md#markdown-toc) option, or as props of [TOC component](./using-vue.md#toc), like ``.
+Rendering of TOC can be configured using the [`themeConfig.toc`](../theme/default-theme-config.md#table-of-contents) option.
+
+> You can also use the official plugin [vuepress-plugin-toc](https://vuepress.github.io/plugins/toc/) for an advanced `` component.
## Custom Containers
diff --git a/packages/docs/docs/guide/using-vue.md b/packages/docs/docs/guide/using-vue.md
index 52d46eb8..636b6c9c 100644
--- a/packages/docs/docs/guide/using-vue.md
+++ b/packages/docs/docs/guide/using-vue.md
@@ -224,28 +224,6 @@ Specify a specific slot for a specific page (.md) for rendering. This will be ve
- [Markdown Slot](./markdown-slot.md)
- [Writing a theme > Content Outlet](../theme/writing-a-theme.md#content-outlet)
-### TOC
-
-- **Props**:
- - `listType` - string or Array, defaults to `"ul"`
- - `includeLevel` - [number, number], defaults to `[2, 3]`
-
-- **Slots**: `header`, `footer`
-
-- **Usage**:
-
-You can add a custom table of contents by specify some props to this component. `includeLevel` decides which level of headers should be included. `listType` decides the tags of lists. If specified as an array, the component will take the first element as the first-level list type and so on. If there are not enough values provided, the last value will be used for all the remaining list types.
-
-``` md
-
- Custom Table of Contents
-
-```
-
-
- Custom Table of Contents
-
-
### Badge
- **Props**:
diff --git a/packages/docs/docs/theme/default-theme-config.md b/packages/docs/docs/theme/default-theme-config.md
index eb1d08df..2cd5839e 100644
--- a/packages/docs/docs/theme/default-theme-config.md
+++ b/packages/docs/docs/theme/default-theme-config.md
@@ -304,6 +304,26 @@ sidebar: false
---
```
+## Table Of Contents
+
+``` js
+// .vuepress/config.js
+module.exports = {
+ themeConfig: {
+ toc: {
+ sidebar: 'auto'
+ }
+ }
+}
+```
+
+Options for [markdown-it-table-of-contents](https://github.com/Oktavilla/markdown-it-table-of-contents#options). The default options are `{ includeLevel: [2, 3] }`.
+
+::: tip
+1. You should always use [`markdown.slugify`](../config/#markdown-slugify) instead of `themeConfig.toc.slugify` if you want to customize header ids.
+2. Setting `themeConfig.toc` to `false` will disable the `[[toc]]` syntax (in case you want to switch to other plugins, such as [vuepress-plugin-toc](https://vuepress.github.io/plugins/toc/)).
+:::
+
## Search Box
### Built-in Search
diff --git a/packages/docs/docs/zh/config/README.md b/packages/docs/docs/zh/config/README.md
index 42db142b..c874c651 100644
--- a/packages/docs/docs/zh/config/README.md
+++ b/packages/docs/docs/zh/config/README.md
@@ -206,21 +206,6 @@ VuePress 提供了一种添加额外样式的简便方法。你可以创建一
这个键值对将会作为特性被增加到是外部链接的 `` 标签上，默认的选项将会在新窗口中打开一个该外部链接。
-### markdown.toc
-
-- 类型: `Object`
-
-这个值将会控制 `[[TOC]]` 默认行为。它包含下面的选项：
-
-- includeLevel: [number, number]，决定哪些级别的标题会被显示在目录中，默认值为 `[2, 3]`。
-- containerClass: string，决定了目录容器的类名，默认值为 `table-of-contents`。
-- markerPattern: RegExp，决定了标题匹配的正则表达式，默认值为 `/^\[\[toc\]\]/im`。
-- listType: string 或 Array，决定了各级列表的标签，默认值为 `"ul"`。
-- containerHeaderHtml: string，在目录开头插入的 HTML 字符串，默认值为 `""`。
-- containerFooterHtml: string，在目录结尾插入的 HTML 字符串，默认值为 `""`。
-
-此外，我们还提供了[全局组件 TOC](../guide/using-vue.md#toc)，可以通过直接向 `` 传递属性实现更加自由的控制。
-
### markdown.plugins
你可以使用 `markdown.plugins` 来安装 markdown-it 插件。它的使用方法与[安装一个 VuePress 插件](../plugin/using-a-plugin.html#using-a-plugin)类似。你可以使用 Babel 语法或对象语法。`markdown-it-` 前缀同样是可以忽略的。
diff --git a/packages/docs/docs/zh/guide/markdown.md b/packages/docs/docs/zh/guide/markdown.md
index f3047871..f2225611 100644
--- a/packages/docs/docs/zh/guide/markdown.md
+++ b/packages/docs/docs/zh/guide/markdown.md
@@ -99,7 +99,7 @@ lang: en-US
:tada: :100:
-## 目录
+## 目录
**输入**
@@ -107,17 +107,13 @@ lang: en-US
[[toc]]
```
-或者
-
-```md
-
-```
-
**输出**
[[toc]]
-目录（Table of Contents）的渲染可以通过 [`markdown.toc`](../config/README.md#markdown-toc) 选项来配置，也可以在 [TOC 组件](./using-vue.md#toc)中直接传入，如 ``。
+目录（Table of Contents）的渲染可以通过 [`themeConfig.toc`](../theme/default-theme-config.md#table-of-contents) 选项来配置。
+
+> 如果想要使用高级的 `` 组件，你也可以使用官方提供的 [vuepress-plugin-toc](https://vuepress.github.io/plugins/toc/) 插件。
## 自定义容器
diff --git a/packages/docs/docs/zh/guide/using-vue.md b/packages/docs/docs/zh/guide/using-vue.md
index 57b758c3..03445335 100644
--- a/packages/docs/docs/zh/guide/using-vue.md
+++ b/packages/docs/docs/zh/guide/using-vue.md
@@ -225,28 +225,6 @@ export default {
- [Markdown 插槽](./markdown-slot.md)
- [开发主题 > 获取渲染内容](../theme/writing-a-theme.md#获取渲染内容)
-### TOC
-
-- **Props**:
- - `listType` - string 或 Array, 默认值为 `"ul"`
- - `includeLevel` - [number, number], 默认值为 `[2, 3]`
-
-- **Slots**: `header`, `footer`
-
-- **Usage**:
-
-你可以通过一些属性来实现一个自定义的目录。`includeLevel` 决定了哪些级别的标题会被显示在目录中。`listType` 决定了所有列表的标签。如果设置为了数组，组件将会使用第一个元素作为第一级列表的标签，以此类推。如果提供的标签不够多，将使用提供的最后一个值作为全部剩下的列表标签。
-
-``` md
-
- 自定义目录
-
-```
-
-
- 自定义目录
-
-
### Badge
- **Props**:
diff --git a/packages/docs/docs/zh/theme/default-theme-config.md b/packages/docs/docs/zh/theme/default-theme-config.md
index 8516cf5f..30f354c0 100644
--- a/packages/docs/docs/zh/theme/default-theme-config.md
+++ b/packages/docs/docs/zh/theme/default-theme-config.md
@@ -299,6 +299,26 @@ sidebar: false
---
```
+## 目录
+
+``` js
+// .vuepress/config.js
+module.exports = {
+ themeConfig: {
+ toc: {
+ sidebar: 'auto'
+ }
+ }
+}
+```
+
+提供给 [markdown-it-table-of-contents](https://github.com/Oktavilla/markdown-it-table-of-contents#options) 的选项。默认选项为 `{ includeLevel: [2, 3] }`。
+
+::: tip
+1. 如果你希望自定义标题，你应该使用 [`markdown.slugify`](../config/#markdown-slugify) 而不是 `themeConfig.toc.slugify`。
+2. 将 `themeConfig.toc` 设为 `false` 将会禁用 `[[toc]]` 的语法（这在当你想要使用诸如 [vuepress-plugin-toc](https://vuepress.github.io/plugins/toc/) 的插件时是有用的）。
+:::
+
## 搜索框
### 内置搜索
diff --git a/yarn.lock b/yarn.lock
index 016e9ba3..acee1e53 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -6587,6 +6587,11 @@ markdown-it-emoji@^1.4.0:
version "1.4.0"
resolved "https://registry.yarnpkg.com/markdown-it-emoji/-/markdown-it-emoji-1.4.0.tgz#9bee0e9a990a963ba96df6980c4fddb05dfb4dcc"
+markdown-it-table-of-contents@^0.4.3:
+ version "0.4.3"
+ resolved "https://registry.yarnpkg.com/markdown-it-table-of-contents/-/markdown-it-table-of-contents-0.4.3.tgz#6453925a76e49b9b3d9569a0d89f1c2168b46982"
+ integrity sha512-x/OdaRzLYxAjmB+jIVlXuE3nX7tZTLDQxm58RkgjTLyQ+I290jYQvPS9cJjVN6SM3U6K6CHKYNgUtPNZmLblYQ==
+
markdown-it@^8.4.1:
version "8.4.2"
resolved "https://registry.yarnpkg.com/markdown-it/-/markdown-it-8.4.2.tgz#386f98998dc15a37722aa7722084f4020bdd9b54"