diff --git a/packages/docs/.remarkrc b/packages/docs/.remarkrc new file mode 100644 index 0000000000..5accdbbae9 --- /dev/null +++ b/packages/docs/.remarkrc @@ -0,0 +1,9 @@ +{ + "plugins": [ + "preset-lint-recommended", + "preset-lint-consistent", + + ["lint-list-item-indent", "space"], + ["lint-heading-style", false] + ] +} diff --git a/packages/docs/docs/guide/deploy.md b/packages/docs/docs/guide/deploy.md index ae81f8a18c..84ec65e953 100644 --- a/packages/docs/docs/guide/deploy.md +++ b/packages/docs/docs/guide/deploy.md @@ -119,8 +119,8 @@ pages: 1. On Netlify, setup up a new project from GitHub with the following settings: - - **Build Command:** `npm run docs:build` or `yarn docs:build` - - **Publish directory:** `docs/.vuepress/dist` +- **Build Command:** `npm run docs:build` or `yarn docs:build` +- **Publish directory:** `docs/.vuepress/dist` 2. Hit the deploy button! @@ -169,18 +169,18 @@ You can also deploy to a [custom domain](http://surge.sh/help/adding-a-custom-do 3. Run `heroku login` and fill in your Heroku credentials: - ``` bash - heroku login - ``` + ``` bash + heroku login + ``` 4. Create a file called `static.json` in the root of your project with the content below: - `static.json`: - ```json - { - "root": "./docs/.vuepress/dist" - } - ``` + `static.json`: + ```json + { + "root": "./docs/.vuepress/dist" + } + ``` This is the configuration of your site. See more at [heroku-buildpack-static](https://github.com/heroku/heroku-buildpack-static). diff --git a/packages/docs/docs/guide/markdown.md b/packages/docs/docs/guide/markdown.md index c9bde4f91e..59fbfba263 100644 --- a/packages/docs/docs/guide/markdown.md +++ b/packages/docs/docs/guide/markdown.md @@ -111,8 +111,12 @@ A list of all emojis available can be found [here](https://github.com/markdown-i **Output** + + [[toc]] + + Rendering of TOC can be configured using the [`markdown.toc`](../config/README.md#markdown-toc) option. ## Custom Containers @@ -311,8 +315,12 @@ It also supports [line highlighting](#line-highlighting-in-code-blocks): **Output** + + <<< @/../@vuepress/markdown/__tests__/fragments/snippet.js{2} + + ::: tip Since the import of the code snippets will be executed before webpack compilation, you can’t use the path alias in webpack. The default value of `@` is `process.cwd()`. ::: diff --git a/packages/docs/docs/guide/permalinks.md b/packages/docs/docs/guide/permalinks.md index 0069a6c7ea..fabf46c86f 100644 --- a/packages/docs/docs/guide/permalinks.md +++ b/packages/docs/docs/guide/permalinks.md @@ -33,7 +33,7 @@ We have seen the shadow of the blog. Let’s continue to look down. ## Permalinks -A permalink is a URL that is intended to remain unchanged for a long time, yielding a hyperlink that is less susceptible to link root[1]. VuePress supports a flexible way to build permalinks, allowing you to use template variables. +A permalink is a URL that is intended to remain unchanged for a long time, yielding a hyperlink that is less susceptible to link root[1][1]. VuePress supports a flexible way to build permalinks, allowing you to use template variables. The default permalink is `/:regular`. @@ -64,11 +64,13 @@ Hello! ### Template Variables | Variable | Description | -|---|---| -|:year|Published year of posts (4-digit)| -|:month|Published month of posts (2-digit)| -|:i_month|Published month of posts (Without leading zeros)| -|:day|Published day of posts (2-digit)| -|:i_day|Published day of posts (Without leading zeros)| -|:slug|Slugified file path (Without extension)| -|:regular| Permalink generated by VuePress by default, for implementation see [here](https://github.com/vuejs/vuepress/blob/master/packages/%40vuepress/shared-utils/src/fileToPath.ts) | +| --- | --- | +| :year | Published year of posts (4-digit) | +| :month | Published month of posts (2-digit) | +| :i_month | Published month of posts (Without leading zeros) | +| :day | Published day of posts (2-digit) | +| :i_day | Published day of posts (Without leading zeros) | +| :slug | Slugified file path (Without extension) | +| :regular | Permalink generated by VuePress by default, for implementation see [here](https://github.com/vuejs/vuepress/blob/master/packages/%40vuepress/shared-utils/src/fileToPath.ts) | + +[1]:https://en.wikipedia.org/wiki/Link_rot diff --git a/packages/docs/docs/guide/using-vue.md b/packages/docs/docs/guide/using-vue.md index d982641abd..923bb30004 100644 --- a/packages/docs/docs/guide/using-vue.md +++ b/packages/docs/docs/guide/using-vue.md @@ -229,9 +229,9 @@ Specify a specific slot for a specific page (.md) for rendering. This will be us - **Props**: - - `text` - string - - `type` - string, optional value: `"tip"|"warn"|"error"`, defaults to `"tip"`. - - `vertical` - string, optional value: `"top"|"middle"`, defaults to `"top"`. + - `text` - string + - `type` - string, optional value: `"tip"|"warn"|"error"`, defaults to `"tip"`. + - `vertical` - string, optional value: `"top"|"middle"`, defaults to `"top"`. - **Usage**: diff --git a/packages/docs/docs/plugin/life-cycle.md b/packages/docs/docs/plugin/life-cycle.md index cfdcea3417..76996bdd9c 100644 --- a/packages/docs/docs/plugin/life-cycle.md +++ b/packages/docs/docs/plugin/life-cycle.md @@ -39,7 +39,7 @@ module.exports = { - Type: `AsyncFunction` - Scope：`build` - Called when a (production) build finishes, with an array of generated page HTML paths. + Called when a (production) build finishes, with an array of generated page HTML paths. ``` js module.exports = { diff --git a/packages/docs/docs/plugin/official/plugin-back-to-top.md b/packages/docs/docs/plugin/official/plugin-back-to-top.md index 3988981873..752fa62d46 100644 --- a/packages/docs/docs/plugin/official/plugin-back-to-top.md +++ b/packages/docs/docs/plugin/official/plugin-back-to-top.md @@ -18,6 +18,6 @@ yarn add -D @vuepress/plugin-back-to-top@next ```javascript module.exports = { - plugins: ['@vuepress/back-to-top'] + plugins: ['@vuepress/back-to-top'] } ``` diff --git a/packages/docs/docs/plugin/official/plugin-google-analytics.md b/packages/docs/docs/plugin/official/plugin-google-analytics.md index 0f56959920..49de62884a 100644 --- a/packages/docs/docs/plugin/official/plugin-google-analytics.md +++ b/packages/docs/docs/plugin/official/plugin-google-analytics.md @@ -20,13 +20,13 @@ yarn add -D @vuepress/plugin-google-analytics@next ```javascript module.exports = { plugins: [ - [ + [ '@vuepress/google-analytics', { 'ga': '' // UA-00000000-0 } - ] - ] + ] + ] } ``` diff --git a/packages/docs/docs/plugin/official/plugin-last-updated.md b/packages/docs/docs/plugin/official/plugin-last-updated.md index 328310472a..f333711844 100644 --- a/packages/docs/docs/plugin/official/plugin-last-updated.md +++ b/packages/docs/docs/plugin/official/plugin-last-updated.md @@ -15,7 +15,7 @@ If you use it at your custom theme, you'll need to handle the UI by yourself, an ```js module.exports = { - plugins: ['@vuepress/last-updated'] + plugins: ['@vuepress/last-updated'] } ``` @@ -35,7 +35,7 @@ const moment = require('moment'); module.exports = { plugins: [ - [ + [ '@vuepress/last-updated', { transformer: (timestamp, lang) => { diff --git a/packages/docs/docs/plugin/official/plugin-nprogress.md b/packages/docs/docs/plugin/official/plugin-nprogress.md index b671745627..eb415d2dfc 100644 --- a/packages/docs/docs/plugin/official/plugin-nprogress.md +++ b/packages/docs/docs/plugin/official/plugin-nprogress.md @@ -34,6 +34,6 @@ Set `$nprogressColor` in your __site__ or __theme__ `palette.styl` file to chang $nprogressColor = red ``` -**Also see:** +__Also see:__ - [Config Reference > Styling](../../config/README.md#styling) diff --git a/packages/docs/docs/plugin/official/plugin-register-components.md b/packages/docs/docs/plugin/official/plugin-register-components.md index d7ce45f51e..db9a984f88 100644 --- a/packages/docs/docs/plugin/official/plugin-register-components.md +++ b/packages/docs/docs/plugin/official/plugin-register-components.md @@ -34,13 +34,13 @@ All components in this directory will be registered as global components, naming ``` js module.exports = { plugins: [ - [ - 'register-components', + [ + 'register-components', { componentsDir: somepath } ] - ] + ] } ``` @@ -54,8 +54,8 @@ Register global components by explicit name and path. ``` js module.exports = { plugins: [ - [ - 'register-components', + [ + 'register-components', { components: [ { diff --git a/packages/docs/docs/plugin/official/plugin-search.md b/packages/docs/docs/plugin/official/plugin-search.md index c8cbd9ccd7..b9e14566aa 100644 --- a/packages/docs/docs/plugin/official/plugin-search.md +++ b/packages/docs/docs/plugin/official/plugin-search.md @@ -27,7 +27,7 @@ Note that this plugin has been included in **default theme**, the search box you module.exports = { plugins: [ ['@vuepress/search', { - searchMaxSuggestions: 10 + searchMaxSuggestions: 10 }] ] } @@ -74,17 +74,17 @@ Set up searchable paths with regular expressions. If no test expression is provi ```bash docs/ -├── .vuepress/ +├── .vuepress/ │ └── ... │ -├── master/ +├── master/ │ └── ... │ -├── 1.0/ +├── 1.0/ │ └── ... │ -└── 2.0/ - └── ... +└── 2.0/ + └── ... ``` You can set up searchable paths with `test` as: diff --git a/packages/docs/docs/theme/inheritance.md b/packages/docs/docs/theme/inheritance.md index 3855e638c1..72f1373c3e 100755 --- a/packages/docs/docs/theme/inheritance.md +++ b/packages/docs/docs/theme/inheritance.md @@ -8,7 +8,7 @@ We have two main reasons to support this feature: 2. In [0.x](https://vuepress.vuejs.org/guide/custom-themes.html#site-and-page-metadata), only one `Layout.vue` is needed for a theme, so we can achieve simple expansion by directly wrapping `Layout.vue` of another theme. - By 1.x, the elements of a theme has become more complex, we have started to have [theme level configuration](./option-api.md), which supports plugins, custom global layout, etc. We have also introduced the [directory structure conventions](./writing-a-theme.md#directory-structure) on theme development, such as `styles/index.styl`, under this background, we can not achieve inheritance as 0.x did. + By 1.x, the elements of a theme has become more complex, we have started to have [theme level configuration](./option-api.md), which supports plugins, custom global layout, etc. We have also introduced the [directory structure conventions](./writing-a-theme.md#directory-structure) on theme development, such as `styles/index.styl`, under this background, we can not achieve inheritance as 0.x did. Consequently, we need to provide a reasonable and reliable theme inheritance strategy. diff --git a/packages/docs/docs/zh/guide/deploy.md b/packages/docs/docs/zh/guide/deploy.md index 4b2e283a58..0eff9e6b3d 100644 --- a/packages/docs/docs/zh/guide/deploy.md +++ b/packages/docs/docs/zh/guide/deploy.md @@ -116,8 +116,8 @@ pages: 1. 在 Netlify 中, 创建一个新的 GitHub 项目，使用以下设置： - - **Build Command:** `npm run build:docs` 或者 `yarn build:docs` - - **Publish directory:** `docs/.vuepress/dist` +- **Build Command:** `npm run build:docs` 或者 `yarn build:docs` +- **Publish directory:** `docs/.vuepress/dist` 2. 点击 deploy 按钮！ @@ -167,9 +167,9 @@ pages: 3. 运行 `heroku login` 并填写你的 Heroku 证书： - ``` bash - heroku login - ``` + ``` bash + heroku login + ``` 4. 在你的项目根目录中，创建一个名为 `static.json` 的文件，并包含下述内容： diff --git a/packages/docs/docs/zh/guide/directory-structure.md b/packages/docs/docs/zh/guide/directory-structure.md index d42571122e..ef25e08535 100644 --- a/packages/docs/docs/zh/guide/directory-structure.md +++ b/packages/docs/docs/zh/guide/directory-structure.md @@ -48,7 +48,7 @@ VuePress 遵循 **“约定优于配置”** 的原则，推荐的目录结构 当你想要去自定义 `templates/ssr.html` 或 `templates/dev.html` 时，最好基于 [默认的模板文件](https://github.com/vuejs/vuepress/blob/master/packages/%40vuepress/core/lib/app/index.dev.html) 来修改，否则可能会导致构建出错。 ::: -**同时阅读:** +**同时阅读:** - [配置](../config/README.md) - [主题](../theme/README.md) diff --git a/packages/docs/docs/zh/guide/markdown.md b/packages/docs/docs/zh/guide/markdown.md index b57acfe1ad..d993862c7e 100644 --- a/packages/docs/docs/zh/guide/markdown.md +++ b/packages/docs/docs/zh/guide/markdown.md @@ -109,8 +109,12 @@ lang: en-US **输出** + + [[toc]] + + 目录（Table of Contents）的渲染可以通过 [`markdown.toc`](../config/README.md#markdown-toc) 选项来配置。 ## 自定义容器 @@ -253,7 +257,7 @@ module.exports = { markdown: { lineNumbers: true } -} +} ``` @@ -299,7 +303,7 @@ module.exports = { 它也支持 [行高亮](#代码块中的行高亮)： ``` md -<<< @/filepath{highlightLines} +<<< @/filepath{highlightLines} ``` **输入** @@ -310,8 +314,12 @@ module.exports = { **输出** + + <<< @/../@vuepress/markdown/__tests__/fragments/snippet.js{2} + + ::: tip 注意 由于代码段的导入将在 webpack 编译之前执行，因此你无法使用 webpack 中的路径别名，此处的 `@` 默认值是 `process.cwd()`。 ::: diff --git a/packages/docs/docs/zh/guide/permalinks.md b/packages/docs/docs/zh/guide/permalinks.md index 4e94cc9dd1..7a28905bcb 100644 --- a/packages/docs/docs/zh/guide/permalinks.md +++ b/packages/docs/docs/zh/guide/permalinks.md @@ -58,13 +58,13 @@ Hello! | 变量 | 介绍 | | --- | --- | -|:year|文章发布的年份 (4数字)| -|:month|文章发布的月份 (2数字)| -|:i_month|文章发布的月份 (前面不带0)| -|:day| 文章发布的日份 (2数字)| -|:i_day|文章发布的日份 (前面不带0)| -|:slug| 蛞蝓化文件路径 (不带扩展名)| -|:regular|VuePress默认的生成永久链接的方式，具体实现看 [这里][2] +| :year | 文章发布的年份 (4数字) | +| :month | 文章发布的月份 (2数字) | +| :i_month | 文章发布的月份 (前面不带0) | +| :day | 文章发布的日份 (2数字) | +| :i_day | 文章发布的日份 (前面不带0) | +| :slug | 蛞蝓化文件路径 (不带扩展名) | +| :regular | VuePress默认的生成永久链接的方式，具体实现看 [这里][2] | [1]:https://en.wikipedia.org/wiki/Link_rot [2]:https://github.com/vuejs/vuepress/blob/master/packages/%40vuepress/shared-utils/src/fileToPath.ts diff --git a/packages/docs/docs/zh/guide/using-vue.md b/packages/docs/docs/zh/guide/using-vue.md index cf6d8b2f22..ee7b2f21e7 100644 --- a/packages/docs/docs/zh/guide/using-vue.md +++ b/packages/docs/docs/zh/guide/using-vue.md @@ -213,7 +213,7 @@ export default { - **Usage**： 指定一个指定页面的特定 slot 用于渲染，当你使用 [自定义布局](../theme/default-theme-config.md#特定页面的自定义布局) 或者自定义主题时，这将非常有用。 - + ``` vue @@ -230,9 +230,9 @@ export default { - **Props**: - - `text` - string - - `type` - string, 可选值： `"tip"|"warn"|"error"`，默认值是： `"tip"` - - `vertical` - string, 可选值： `"top"|"middle"`，默认值是： `"top"` + - `text` - string + - `type` - string, 可选值： `"tip"|"warn"|"error"`，默认值是： `"tip"` + - `vertical` - string, 可选值： `"top"|"middle"`，默认值是： `"top"` - **Usage**: diff --git a/packages/docs/docs/zh/miscellaneous/design-concepts.md b/packages/docs/docs/zh/miscellaneous/design-concepts.md index 33cde8b811..baa30a29fc 100644 --- a/packages/docs/docs/zh/miscellaneous/design-concepts.md +++ b/packages/docs/docs/zh/miscellaneous/design-concepts.md @@ -179,7 +179,7 @@ module.exports = { plugins: [ 'vuepress-plugin-xxx', { name: 'bar' } - ] + ] } ``` diff --git a/packages/docs/docs/zh/miscellaneous/migration-guide.md b/packages/docs/docs/zh/miscellaneous/migration-guide.md index 66031ee0f9..6fecd06e9b 100644 --- a/packages/docs/docs/zh/miscellaneous/migration-guide.md +++ b/packages/docs/docs/zh/miscellaneous/migration-guide.md @@ -10,7 +10,7 @@ sidebar: auto GA 已经被分离为一个单独的插件 [@vuepress/plugin-google-analytics](../plugin/official/plugin-google-analytics.md)。 -::: upgrade +::: upgrade 1. 安装 `@vuepress/plugin-google-analytics`: diff --git a/packages/docs/docs/zh/plugin/official/plugin-back-to-top.md b/packages/docs/docs/zh/plugin/official/plugin-back-to-top.md index fa9b73bf2f..c617ff9c2a 100644 --- a/packages/docs/docs/zh/plugin/official/plugin-back-to-top.md +++ b/packages/docs/docs/zh/plugin/official/plugin-back-to-top.md @@ -18,6 +18,6 @@ yarn add -D @vuepress/plugin-back-to-top@next ```javascript module.exports = { - plugins: ['@vuepress/back-to-top'] + plugins: ['@vuepress/back-to-top'] } ``` diff --git a/packages/docs/docs/zh/plugin/official/plugin-google-analytics.md b/packages/docs/docs/zh/plugin/official/plugin-google-analytics.md index f04ec79bda..6c80a0281e 100644 --- a/packages/docs/docs/zh/plugin/official/plugin-google-analytics.md +++ b/packages/docs/docs/zh/plugin/official/plugin-google-analytics.md @@ -19,13 +19,13 @@ yarn add -D @vuepress/plugin-google-analytics@next ```javascript module.exports = { plugins: [ - [ + [ '@vuepress/google-analytics', { 'ga': '' // UA-00000000-0 } - ] - ] + ] + ] } ``` diff --git a/packages/docs/docs/zh/plugin/official/plugin-last-updated.md b/packages/docs/docs/zh/plugin/official/plugin-last-updated.md index 517c4f3bfb..310590a60b 100644 --- a/packages/docs/docs/zh/plugin/official/plugin-last-updated.md +++ b/packages/docs/docs/zh/plugin/official/plugin-last-updated.md @@ -15,7 +15,7 @@ metaTitle: Last-Updated 插件 | VuePress ```js module.exports = { - plugins: ['@vuepress/last-updated'] + plugins: ['@vuepress/last-updated'] } ``` @@ -35,7 +35,7 @@ const moment = require('moment'); module.exports = { plugins: [ - [ + [ '@vuepress/last-updated', { transformer: (timestamp, lang) => { diff --git a/packages/docs/docs/zh/plugin/official/plugin-nprogress.md b/packages/docs/docs/zh/plugin/official/plugin-nprogress.md index 6f33b1a824..a8a3296ebe 100644 --- a/packages/docs/docs/zh/plugin/official/plugin-nprogress.md +++ b/packages/docs/docs/zh/plugin/official/plugin-nprogress.md @@ -34,6 +34,6 @@ module.exports = { $nprogressColor = red ``` -**参考：** +__参考：__ - [配置 > Styling](../../config/README.md#styling) diff --git a/packages/docs/docs/zh/plugin/official/plugin-pwa.md b/packages/docs/docs/zh/plugin/official/plugin-pwa.md index 6823f641f0..f29819c330 100644 --- a/packages/docs/docs/zh/plugin/official/plugin-pwa.md +++ b/packages/docs/docs/zh/plugin/official/plugin-pwa.md @@ -74,7 +74,7 @@ type popupConfig = normalPopupConfig | localedPopupConfig 本选项开启了一个用于刷新内容的弹窗。这个弹窗将会在站点有内容更新时显示出来，并提供了一个 `refresh` 按钮，允许用户立即刷新内容。 ->如果没有“刷新”按钮，则只有在所有的 [Clients](https://developer.mozilla.org/en-US/docs/Web/API/Clients) 被关闭后，新的 Service Worker 才会处于活动状态。这意味着用户在关闭你网站的所有标签之前无法看到新内容。但是 `refresh` 按钮会立即激活新的 Service Worker。 +> 如果没有“刷新”按钮，则只有在所有的 [Clients](https://developer.mozilla.org/en-US/docs/Web/API/Clients) 被关闭后，新的 Service Worker 才会处于活动状态。这意味着用户在关闭你网站的所有标签之前无法看到新内容。但是 `refresh` 按钮会立即激活新的 Service Worker。 ### popupComponent @@ -104,9 +104,9 @@ module.exports = { module.exports = { themeConfig: { - serviceWorker: { -- updatePopup: { -- message: "New content is available.", -- buttonText: "Refresh" +- updatePopup: { +- message: "New content is available.", +- buttonText: "Refresh" - } - } }, diff --git a/packages/docs/docs/zh/plugin/official/plugin-register-components.md b/packages/docs/docs/zh/plugin/official/plugin-register-components.md index 86a58d9243..b887627144 100644 --- a/packages/docs/docs/zh/plugin/official/plugin-register-components.md +++ b/packages/docs/docs/zh/plugin/official/plugin-register-components.md @@ -34,13 +34,13 @@ module.exports = { ``` js module.exports = { plugins: [ - [ - 'register-components', + [ + 'register-components', { componentsDir: somepath } ] - ] + ] } ``` @@ -54,8 +54,8 @@ module.exports = { ``` js module.exports = { plugins: [ - [ - 'register-components', + [ + 'register-components', { components: [ { diff --git a/packages/docs/docs/zh/theme/inheritance.md b/packages/docs/docs/zh/theme/inheritance.md index cc0816b36b..bbb3e6346d 100755 --- a/packages/docs/docs/zh/theme/inheritance.md +++ b/packages/docs/docs/zh/theme/inheritance.md @@ -6,7 +6,7 @@ 1. VuePress 为开发者提供了一个[默认主题](./default-theme-config.md)，它能在大多数场景下满足了文档编写者的需求。即便如此，仍然还是会有不少用户选择将其 eject 出来进行修改，即使他们可能只是想要修改其中的某个组件。 2. 在 [0.x](https://vuepress.vuejs.org/guide/custom-themes.html#site-and-page-metadata) 中，主题的入口只需要一个 `Layout.vue`，所以我们可以通过包装另一个主题的 `Layout.vue` 来实现简单的拓展。 - + 到了 1.x 中，一个主题的元素开始变得复杂，我们开始有了[主题级别的配置](./option-api.md)，它支持为主题添加插件、自定义 GlobalLayout 等。除此之外，我们还有一些引入了主题开发的 [目录结构的约定](./writing-a-theme.md#目录结构)，如 `styles/index.styl`，在这样的背景下，我们无法使用 0.x 的方式来实现继承了。 因此，我们需要提供一种合理、可靠的主题继承方案。 @@ -122,7 +122,7 @@ theme │   └── `Layout.vue` ├── package.json └── index.js -::: +::: 那么，在该主题中的任意 Vue 组件中，**你都应该通过 `@theme` 来访问主题根目录**： @@ -139,7 +139,7 @@ import Home from '@theme/components/Navbar.vue' theme └── components    └── `Navbar.vue` -::: +::: `@theme/components/Navbar.vue` 会自动地映射到子主题中的 Navbar 组件，当你移除这个组件时，`@theme/components/Navbar.vue` 又会自动恢复为父主题中的 Navbar 组件。 diff --git a/packages/docs/docs/zh/theme/option-api.md b/packages/docs/docs/zh/theme/option-api.md index 4485fe347a..70d336c04e 100755 --- a/packages/docs/docs/zh/theme/option-api.md +++ b/packages/docs/docs/zh/theme/option-api.md @@ -95,7 +95,7 @@ module.exports = { 举例来说，当你想为当前主题设置全局的 header 和 footer 时，你可以这样做： - + ```vue