home/vuepress
2
0
Fork 0
mirror of https://github.com/wahyd4/vuepress.git synced 2026-08-09 05:16:23 +10:00
Code Issues Packages Projects Releases Wiki Activity

docs: documentation linting (#1745)

Browse Source 
* chore: install textlint

* chore: add textlint rules

* feat: set up configuration file and command

* fix: run textlint on files

* chore: lint .textlintrc.js

* chore: add custom terms

* chore: add comment filter

* fix: fix frontmatter term

* chore: set subjective rules to warning severity

* fix: manually fix issues

* chore: add script as pre-commit hook
This commit is contained in:
Sarah Dayan
2019-08-07 23:24:58 +08:00
committed by ULIVZ
parent f6a2fb9f72
commit 8039f421f7
36 changed files with 1232 additions and 261 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.lintstagedrc
+3
View File
@@ -0,0 +1,3 @@
{
"*.{js,vue}": ["eslint --fix", "git add"]
}
package.json
+10 -11
View File
@@ -7,6 +7,7 @@
],
"description": "Minimalistic doc generator with Vue component based layout system",
"scripts": {
"precommit": "lint-staged",
"bootstrap": "yarn && lerna bootstrap && yarn tsc",
"clean": "lerna clean && rm -rf node_modules",
"boot": "node scripts/bootstrap.js",
@@ -24,25 +25,23 @@
"test": "node scripts/test.js",
"tsc": "lerna run tsc"
},
"gitHooks": {
"pre-commit": "lint-staged"
},
"lint-staged": {
"*.{js,vue}": [
"eslint --fix",
"git add"
]
},
"devDependencies": {
"@types/escape-html": "^0.0.20",
"@types/fs-extra": "^5.0.4",
"@types/globby": "^9.1.0",
"@types/hash-sum": "^1.0.0",
"@types/lru-cache": "^4.1.1",
"@types/node": "^10.12.12",
"@types/semver": "^6.0.0",
"conventional-changelog-cli": "^2.0.21",
"eslint": "^4.19.1",
"eslint-plugin-jest": "^21.15.1",
"eslint-plugin-vue-libs": "^3.0.0",
"husky": "^3.0.2",
"inquirer": "^6.2.0",
"lerna": "3.13.4",
"lint-staged": "^8.1.5",
"minimist": "^1.2.0",
"yorkie": "^2.0.0",
"inquirer": "^6.2.0",
"typescript": "^3.2.2",
"@types/node": "^10.12.12",
"@types/lru-cache": "^4.1.1",
packages/docs/.lintstagedrc
+3
View File
@@ -0,0 +1,3 @@
{
"docs/**/*.md": ["yarn lint-md", "git add"]
}
packages/docs/.textlint.terms.json
+8
View File
@@ -0,0 +1,8 @@
[
"Stylus",
"VuePress",
[
"front[- ]matter",
"frontmatter"
]
]
packages/docs/.textlintrc.js
+23
View File
@@ -0,0 +1,23 @@
module.exports = {
rules: {
'@textlint-rule/no-unmatched-pair': true,
apostrophe: true,
'common-misspellings': true,
diacritics: true,
'en-capitalization': {
allowHeading: false
},
'stop-words': {
severity: 'warning'
},
terminology: {
terms: `${__dirname}/.textlint.terms.json`
},
'write-good': {
severity: 'warning'
}
},
filters: {
comments: true
}
}
packages/docs/docs/api/cli.md
+2 -2
View File
@@ -1,4 +1,4 @@
# Command Line Interface
# Command-line Interface
## Usage
@@ -40,7 +40,7 @@ See [host](../config/README.md#host).
Open browser when ready.
### --no-clear-screen
do not clear screen when dev server is ready.
Do not clear screen when dev server is ready.
## eject
packages/docs/docs/api/node.md
+4 -4
View File
@@ -14,7 +14,7 @@ Create a VuePress application.
#### App.prototype.process: () => Promise\<void> | never
A asynchronous method used to prepare the context of the current app. which contains loading pages and plugins, apply plugins, etc.
An asynchronous method used to prepare the context of the current app, and which contains loading pages and plugins, apply plugins, etc.
#### App.prototype.dev: () => Promise\<App> | never
@@ -27,7 +27,7 @@ Launch a build process with current app context.
### dev(\[options]): Promise\<App>
Start a development server, actually it's implemented by `createApp`:
Start a development server, actually it’s implemented by `createApp`:
```js
async function dev (options) {
@@ -39,7 +39,7 @@ async function dev (options) {
### build(\[options]): Promise\<App>
Build your source files as a static site, actually it's implemented by `createApp`:
Build your source files as a static site, actually it’s implemented by `createApp`:
```js
async function build (options) {
@@ -96,4 +96,4 @@ See [dest](../config/README.md#dest).
- Type: `object`
- Required: `{}`
It's very useful when you're writing tests and don't want to depend on actual config file, for all options please head [siteConfig](../config/README.md).
It’s useful when you’re writing tests and don’t want to depend on actual config file, for all options please head [siteConfig](../config/README.md).
packages/docs/docs/config/README.md
+21 -21
View File
@@ -14,7 +14,7 @@ sidebar: auto
- Type: `string`
- Default: `/`
The base URL the site will be deployed at. You will need to set this if you plan to deploy your site under a sub path, for example, GitHub pages. If you plan to deploy your site to `https://foo.github.io/bar/`, then `base` should be set to `"/bar/"`. It should always start and end with a slash.
The base URL the site will be deployed at. You will need to set this if you plan to deploy your site under a sub path, for example, GitHub pages. If you plan to deploy your site to `https://foo.github.io/bar/`, then you should set `base` to `"/bar/"`. It should always start and end with a slash.
The `base` is automatically prepended to all the URLs that start with `/` in other options, so you only need to specify it once.
@@ -35,14 +35,14 @@ Title for the site. This will be the prefix for all page titles, and displayed i
- Type: `string`
- Default: `undefined`
Description for the site. This will be rendered as a `<meta>` tag in the page HTML.
Description for the site. This will render as a `<meta>` tag in the page HTML.
### head
- Type: `Array`
- Default: `[]`
Extra tags to be injected to the page HTML `<head>`. Each tag can be specified in the form of `[tagName, { attrName: attrValue }, innerHTML?]`. For example, to add a custom favicon:
Extra tags to inject into the page HTML `<head>`. You can specify each tag in the form of `[tagName, { attrName: attrValue }, innerHTML?]`. For example, to add a custom favicon:
``` js
module.exports = {
@@ -102,10 +102,10 @@ A function to control what files should have `<link rel="preload">` resource hin
VuePress uses [cache-loader](https://github.com/webpack-contrib/cache-loader) by default to greatly speed up the compilation of webpack.
This option can be used to specify the path to the cache, and can also remove the cache before each build by setting it to `false`.
You can use this option to specify the path to the cache, and can also remove the cache before each build by setting it to `false`.
::: tip
This option can also be used through the CLI:
You can also use this option through the CLI:
```bash
vuepress dev docs --cache .cache # set cache path
@@ -118,7 +118,7 @@ vuepress dev docs --no-cache # remove cache before each build.
- Type: `Array`
- Default: `[]`
Specify extra files to be watched.
Specify extra files to watch.
You can watch any file if you want. File changes will trigger `vuepress` rebuilding and real-time updates.
@@ -135,9 +135,9 @@ module.exports = {
### palette.styl
If you wish to apply simple color overrides to the styling of the [default preset](https://github.com/vuejs/vuepress/blob/master/packages/@vuepress/core/lib/client/style/config.styl) or define some color variables for using later, you can create an `.vuepress/styles/palette.styl` file.
To apply simple color overrides to the styling of the [default preset](https://github.com/vuejs/vuepress/blob/master/packages/@vuepress/core/lib/client/style/config.styl) or define some color variables for using later, you can create a `.vuepress/styles/palette.styl` file.
There are a few color variables you can tweak:
There are some color variables you can tweak:
``` stylus
// showing default values
@@ -148,12 +148,12 @@ $codeBgColor = #282c34
```
::: danger Note
You should ONLY write color variables in this file. since `palette.styl` will be imported at the end of the root stylus config file, as a config, it will be used by multiple files, so once you wrote styles here, your style would be duplicated by multiple times.
You should ONLY write color variables in this file. Since `palette.styl` will be imported at the end of the root Stylus config file, as a config, several files will use it, so once you wrote styles here, your style would be duplicated by multiple times.
:::
### index.styl
VuePress provides a convenient way to add extra styles. you can create an `.vuepress/styles/index.styl` file for that. This is a [Stylus](http://stylus-lang.com/) file but you can use normal CSS syntax as well.
VuePress provides a convenient way to add extra styles. You can create a `.vuepress/styles/index.styl` file for that. This is a [Stylus](http://stylus-lang.com/) file but you can use normal CSS syntax as well.
```stylus
.content {
@@ -163,7 +163,7 @@ VuePress provides a convenient way to add extra styles. you can create an `.vuep
**Also see:**
- [Why can't `palette.styl` and `index.styl` merge into one API?](../faq/README.md#why-can-t-palette-styl-and-index-styl-merge-into-one-api)
- [Why can’t `palette.styl` and `index.styl` merge into one API?](../faq/README.md#why-can-t-palette-styl-and-index-styl-merge-into-one-api)
## Theming
@@ -196,7 +196,7 @@ Provide config options to the used theme. The options will vary depending on the
- Type: `Object|Array`
- Default: `undefined`
Please refer to [Plugin > Using a plugin](../plugin/using-a-plugin.md) to learn how to use a plugin.
Please check out [Plugin > Using a plugin](../plugin/using-a-plugin.md) to learn how to use a plugin.
## Markdown
@@ -223,7 +223,7 @@ Function for transforming [header](../miscellaneous/glossary.md#headers) texts i
- Type: `Object`
- Default: `{ permalink: true, permalinkBefore: true, permalinkSymbol: '#' }`
Options for [markdown-it-anchor](https://github.com/valeriangalliat/markdown-it-anchor). (Note: prefer `markdown.slugify` if you want to customize header ids.)
Options for [markdown-it-anchor](https://github.com/valeriangalliat/markdown-it-anchor). (Note: prefer `markdown.slugify` to customize header ids.)
### markdown.externalLinks
@@ -237,11 +237,11 @@ The key and value pair will be added to `<a>` tags that point to an external lin
- Type: `Object`
- Default: `{ includeLevel: [2, 3] }`
Options for [markdown-it-table-of-contents](https://github.com/Oktavilla/markdown-it-table-of-contents). (Note: prefer `markdown.slugify` if you want to customize header ids.)
Options for [markdown-it-table-of-contents](https://github.com/Oktavilla/markdown-it-table-of-contents). (Note: prefer `markdown.slugify` to customize header ids.)
### 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.
You can install any markdown-it plugins through `markdown.plugins` option. It’s 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.
``` js
module.exports = {
@@ -256,7 +256,7 @@ module.exports = {
}
```
or
Or
``` js
module.exports = {
@@ -276,7 +276,7 @@ module.exports = {
- Type: `Function`
- Default: `undefined`
A function to modify default config or apply additional plugins to the [markdown-it](https://github.com/markdown-it/markdown-it) instance used to render source files. e.g.
A function to edit default config or apply extra plugins to the [markdown-it](https://github.com/markdown-it/markdown-it) instance used to render source files. For example:
``` js
module.exports = {
@@ -306,7 +306,7 @@ VuePress comes with built-in webpack config for the CSS pre-processors listed be
Options for [postcss-loader](https://github.com/postcss/postcss-loader). Note specifying this value will overwrite autoprefixer and you will need to include it yourself.
### stylus
### Stylus
- Type: `Object`
- Default: `{ preferPathResolver: 'webpack' }`
@@ -320,7 +320,7 @@ Options for [stylus-loader](https://github.com/shama/stylus-loader).
Options for [sass-loader](https://github.com/webpack-contrib/sass-loader) to load `*.scss` files.
### sass
### Sass
- Type: `Object`
- Default: `{ indentedSyntax: true }`
@@ -339,7 +339,7 @@ Options for [less-loader](https://github.com/webpack-contrib/less-loader).
- Type: `Object | Function`
- Default: `undefined`
Modify the internal webpack config. If the value is an Object, it will be merged into the final config using [webpack-merge](https://github.com/survivejs/webpack-merge); If the value is a function, it will receive the config as the 1st argument and an `isServer` flag as the 2nd argument. You can either mutate the config directly, or return an object to be merged:
Edit the internal webpack config. If the value is an Object, it will be merged into the final config using [webpack-merge](https://github.com/survivejs/webpack-merge); If the value is a function, it will receive the config as the 1st argument and an `isServer` flag as the 2nd argument. You can either mutate the config directly, or return an object to merge:
``` js
module.exports = {
@@ -356,7 +356,7 @@ module.exports = {
- Type: `Function`
- Default: `undefined`
Modify the internal webpack config with [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain).
Edit the internal webpack config with [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain).
``` js
module.exports = {
packages/docs/docs/faq/README.md
+11 -11
View File
@@ -4,13 +4,13 @@ sidebar: auto
# FAQ
## Why can't `palette.styl` and `index.styl` merge into one API?
## Why can’t `palette.styl` and `index.styl` merge into one API?
The `palette.styl` is responsible for global color settings. During compilation, theme color constants should be resolved by the preprocessor first and then be applied to the global context.
The `palette.styl` is responsible for global color settings. During compilation, theme color constants should be resolved by the preprocessor first and then be applied to the global context.
But for `index.styl`. its job is to override the default styles of application. According to the priority principle of css, the later style has a higher priority, so it should be generated at the end of the CSS file.
But for `index.styl`, its job is to override the default styles of application. According to the priority principle of CSS, the later style has a higher priority, so it should be generated at the end of the CSS file.
A simple diagram describing the stylus compiler's compilation order as follows:
A simple diagram describing the Stylus compiler’s compilation order as follows:
@flowstart
stage1=>operation: palette.styl
@@ -22,11 +22,11 @@ stage1->stage2->stage3
<br>
## What's the differences between the `clientDynamicModules` and `enhanceAppFiles`?
## What’s the differences between the `clientDynamicModules` and `enhanceAppFiles`?
Let's take a look back first, both `clientDynamicModules` and `enhanceAppFiles` can generate modules with dynamic javascript code during compile time.
Let’s take a look back first, both `clientDynamicModules` and `enhanceAppFiles` can generate modules with dynamic JavaScript code during compile time.
The difference is that the files generated by `enhanceAppFiles` will be loaded and applied automatically when the application is initialized on the client side. While the files generated by `clientDynamicModules` needs to be imported as `@dynamic/xxx` by the users themselves.
The difference is that the files generated by `enhanceAppFiles` will be loaded and applied automatically when the application is initialized on the client-side, while the files generated by `clientDynamicModules` need to be imported as `@dynamic/xxx` by the users themselves.
```js
module.exports = (options, ctx) => ({
@@ -48,12 +48,12 @@ module.exports = (options, ctx) => ({
## When do I need to use `enhanceAppFiles`?
1. I want to execute some code on the client side automatically.
2. I don't have a need for reuse of this module.
1. I want to execute some code on the client-side automatically.
2. I don’t need to reuse this module.
**Example:**
- [@vuepress/plugin-register-components](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/plugin-register-components/index.js#L24): Automatically registering components on the client side.
- [@vuepress/plugin-register-components](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/plugin-register-components/index.js#L24): Automatically registering components on the client-side.
- [@vuepress/plugin-pagination](https://github.com/vuejs/vuepress/blob/master/packages/@vuepress/plugin-pagination/index.js#L14): Automatically insert Vue plugins to expand the API of the client.
## When do I need to use `clientDynamicModules`?
@@ -63,5 +63,5 @@ module.exports = (options, ctx) => ({
**Example:**
- [@vuepress/plugin-blog](https://github.com/ulivz/vuepress-plugin-blog/blob/master/src/index.ts#L167): Using compile-time metadata to generate some dynamic blog-related modules and initialize them on the client side by using `enhanceAppFiles`.
- [@vuepress/plugin-blog](https://github.com/ulivz/vuepress-plugin-blog/blob/master/src/index.ts#L167): Using compile-time metadata to generate some dynamic blog-related modules and initialize them on the client-side by using `enhanceAppFiles`.
packages/docs/docs/guide/README.md
+9 -9
View File
@@ -2,21 +2,21 @@
<Bit/>
VuePress is composed of two parts: a [minimalistic static site generator](https://github.com/vuejs/vuepress/tree/master/packages/%40vuepress/core) with a Vue-powered [theming system](../theme/README.md) and [Plugin API](../plugin/README.md), and a [default theme](../theme/default-theme-config.md) optimized for writing technical documentation. It was created to support the documentation needs of Vue's own sub projects.
VuePress is composed of two parts: a [minimalistic static site generator](https://github.com/vuejs/vuepress/tree/master/packages/%40vuepress/core) with a Vue-powered [theming system](../theme/README.md) and [Plugin API](../plugin/README.md), and a [default theme](../theme/default-theme-config.md) optimized for writing technical documentation. It was created to support the documentation needs of Vue’s own sub projects.
Each page generated by VuePress has its own pre-rendered static HTML, providing great loading performance and is SEO-friendly. Once the page is loaded, however, Vue takes over the static content and turns it into a full Single-Page Application (SPA). Additional pages are fetched on demand as the user navigates around the site.
Each page generated by VuePress has its own pre-rendered static HTML, providing great loading performance and is SEO-friendly. Yet, once the page is loaded, Vue takes over the static content and turns it into a full Single-Page Application (SPA). Extra pages are fetched on demand as the user navigates around the site.
## How It Works
A VuePress site is in fact a SPA powered by [Vue](http://vuejs.org/), [Vue Router](https://github.com/vuejs/vue-router) and [webpack](http://webpack.js.org/). If you've used Vue before, you will notice the familiar development experience when you are writing or developing custom themes (you can even use Vue DevTools to debug your custom theme!).
A VuePress site is in fact a SPA powered by [Vue](http://vuejs.org/), [Vue Router](https://github.com/vuejs/vue-router) and [webpack](http://webpack.js.org/). If you’ve used Vue before, you will notice the familiar development experience when you are writing or developing custom themes (you can even use Vue DevTools to debug your custom theme!).
During the build, we create a server-rendered version of the app and render the corresponding HTML by virtually visiting each route. This approach is inspired by [Nuxt](https://nuxtjs.org/)'s `nuxt generate` command and other projects like [Gatsby](https://www.gatsbyjs.org/).
Each markdown file is compiled into HTML with [markdown-it](https://github.com/markdown-it/markdown-it) and then processed as the template of a Vue component. This allows you to directly use Vue inside your markdown files and is great when you need to embed dynamic content.
Each Markdown file is compiled into HTML with [markdown-it](https://github.com/markdown-it/markdown-it) and then processed as the template of a Vue component. This allows you to directly use Vue inside your Markdown files and is great when you need to embed dynamic content.
## Features
**Built-in markdown extensions**
**Built-in Markdown extensions**
* [Table of Contents](../guide/markdown.md#table-of-contents)
* [Custom Containers](../guide/markdown.md#custom-containers)
@@ -65,16 +65,16 @@ Each markdown file is compiled into HTML with [markdown-it](https://github.com/m
### Nuxt
Nuxt is capable of doing what VuePress does, but it is designed for building applications. VuePress is focused on content-centric static sites and provides features tailored for technical documentation out of the box.
Nuxt is capable of doing what VuePress does, but it’s designed for building applications. VuePress is focused on content-centric static sites and provides features tailored for technical documentation out of the box.
### Docsify / Docute
Both are great projects and also Vue-powered. Except they are both completely runtime-driven and therefore not SEO-friendly. If you don't care about SEO and don't want to mess with installing dependencies, these are still great choices.
Both are great projects and also Vue-powered. Except they are both fully runtime-driven and therefore not SEO-friendly. If you don’t care for SEO and don’t want to mess with installing dependencies, these are still great choices.
### Hexo
Hexo has been serving the Vue docs well - in fact, we are probably still a long way to go from migrating away from it for our main site. The biggest problem is that its theming system is very static and string-based - we really want to leverage Vue for both the layout and the interactivity. Also, Hexo's markdown rendering isn't the most flexible to configure.
Hexo has been serving the Vue docs well - in fact, we are probably still a long way to go from migrating away from it for our main site. The biggest problem is that its theming system is static and string-based - we want to take advantage of Vue for both the layout and the interactivity. Also, Hexo’s Markdown rendering isn’t the most flexible to configure.
### GitBook
We've been using GitBook for most of our sub project docs. The primary problem with GitBook is that its development reload performance is intolerable with a large amount of files. The default theme also has a pretty limiting navigation structure, and the theming system is, again, not Vue based. The team behind GitBook is also more focused on turning it into a commercial product rather than an open-source tool.
We’ve been using GitBook for most of our sub project docs. The primary problem with GitBook is that its development reload performance is intolerable with a large amount of files. The default theme also has a pretty limiting navigation structure, and the theming system is, again, not Vue based. The team behind GitBook is also more focused on turning it into a commercial product rather than an open-source tool.
packages/docs/docs/guide/assets.md
+7 -7
View File
@@ -2,7 +2,7 @@
## Relative URLs
All markdown files are compiled into Vue components and processed by webpack, therefore you can and **should prefer** referencing any asset using relative URLs:
All Markdown files are compiled into Vue components and processed by webpack, so you can and **should prefer** referencing any asset using relative URLs:
``` md
![An image](./image.png)
@@ -10,14 +10,14 @@ All markdown files are compiled into Vue components and processed by webpack, th
This would work the same way as in `*.vue` file templates. The image will be processed with `url-loader` and `file-loader`, and copied to appropriate locations in the generated static build.
In addition, you can use the `~` prefix to explicitly indicate this is a webpack module request, allowing you to reference files with webpack aliases or from npm dependencies:
Also, you can use the `~` prefix to explicitly specify this is a webpack module request, allowing you to reference files with webpack aliases or from npm dependencies:
``` md
![Image from alias](~@alias/image.png)
![Image from dependency](~some-dependency/image.png)
```
webpack aliases can be configured via [configureWebpack](../config/README.md#configurewebpack) in `.vuepress/config.js`. Example:
Webpack aliases can be configured via [configureWebpack](../config/README.md#configurewebpack) in `.vuepress/config.js`. Example:
``` js
module.exports = {
@@ -33,18 +33,18 @@ module.exports = {
## Public Files
Sometimes you may need to provide static assets that are not directly referenced in any of your markdown or theme components - for example, favicons and PWA icons. In such cases, you can put them inside `.vuepress/public` and they will be copied to the root of the generated directory.
Sometimes you may need to provide static assets that are not directly referenced in any of your Markdown or theme components - for example, favicons and PWA icons. In such cases, you can put them inside `.vuepress/public` and they will be copied to the root of the generated directory.
## Base URL
If your site is deployed to a non-root URL, you will need to set the `base` option in `.vuepress/config.js`. For example, if you plan to deploy your site to `https://foo.github.io/bar/`, then `base` should be set to `"/bar/"` (it should always start and end with a slash).
With a base URL, if you want to reference an image in `.vuepress/public`, you'd have to use URLs like `/bar/image.png`. However, this is brittle if you ever decide to change the `base` later. To help with that, VuePress provides a built-in helper `$withBase` (injected onto Vue's prototype) that generates the correct path:
With a base URL, to reference an image in `.vuepress/public`, you’d have to use URLs like `/bar/image.png`. Yet, this is brittle if you ever decide to change the `base` later. To help with that, VuePress provides a built-in helper `$withBase` (injected onto Vue’s prototype) that generates the correct path:
``` vue
<img :src="$withBase('/foo.png')" alt="foo">
```
Note you can use the above syntax not only in theme components, but in your markdown files as well.
Note you can use the above syntax not only in theme components, but in your Markdown files as well.
In addition, if a `base` is set, it is automatically prepended to all asset URLs in `.vuepress/config.js` options.
Also, if a `base` is set, it’s automatically prepended to all asset URLs in `.vuepress/config.js` options.
packages/docs/docs/guide/basic-config.md
+6 -6
View File
@@ -2,7 +2,7 @@
## Config File
Without any configuration, the page is pretty minimal, and the user has no way to navigate around the site. To customize your site, let's first create a `.vuepress` directory inside your docs directory. This is where all VuePress-specific files will be placed in. Your project structure is probably like this:
Without any configuration, the page is pretty minimal, and the user has no way to navigate around the site. To customize your site, let’s first create a `.vuepress` directory inside your docs directory. This is where all VuePress-specific files will be placed in. Your project structure is probably like this:
```
.
@@ -22,9 +22,9 @@ module.exports = {
}
```
If you've got the dev server running, you should see the page now has a header with the title and a search box. VuePress comes with built-in headers-based search - it automatically builds a simple search index from the title, `h2` and `h3` headers from all the pages.
If you’ve got the dev server running, you should see the page now has a header with the title and a search box. VuePress comes with built-in headers-based search - it automatically builds a simple search index from the title, `h2` and `h3` headers from all the pages.
Consult the [Config Reference](../config/README.md) for a full list of options.
Check out the [Config Reference](../config/README.md) for a full list of options.
::: tip Alternative Config Formats
You can also use YAML (`.vuepress/config.yml`) or TOML (`.vuepress/config.toml`) formats for the configuration file.
@@ -32,13 +32,13 @@ You can also use YAML (`.vuepress/config.yml`) or TOML (`.vuepress/config.toml`)
## Theme Configuration
A VuePress theme is responsible for all the layout and interactivity details of your site. VuePress ships with a default theme (you are looking at it right now) which is designed for technical documentation. It exposes a number of options that allow you to customize the navbar, sidebar and homepage, etc. For details, check out the [Default Theme Config](../theme/default-theme-config.md) page.
A VuePress theme owns all the layout and interactivity details of your site. VuePress ships with a default theme (you are looking at it right now), designed for technical documentation. It exposes many options that allow you to customize the navbar, sidebar and homepage, etc. For details, check out the [Default Theme Config](../theme/default-theme-config.md) page.
If you wish to develop a custom theme, see [Writing a theme](../theme/writing-a-theme.md).
To develop a custom theme, see [Writing a theme](../theme/writing-a-theme.md).
## App Level Enhancements
Since the VuePress app is a standard Vue app, you can apply app-level enhancements by creating a file `.vuepress/enhanceApp.js`, which will be imported into the app if it is present. The file should `export default` a hook function which will receive an object containing some app-level values. You can use this hook to install additional Vue plugins, register global components, or add additional router hooks:
Since the VuePress app is a standard Vue app, you can apply app-level enhancements by creating a file `.vuepress/enhanceApp.js`, which will be imported into the app if it’s present. The file should `export default` a hook function which will receive an object containing some app-level values. You can use this hook to install extra Vue plugins, register global components, or add extra router hooks:
``` js
export default ({
packages/docs/docs/guide/deploy.md
+7 -7
View File
@@ -1,6 +1,6 @@
# Deploying
The following guides are based on a few shared assumptions:
The following guides are based on some shared assumptions:
- You are placing your docs inside the `docs` directory of your project;
- You are using the default build output location (`.vuepress/dist`);
@@ -20,7 +20,7 @@ The following guides are based on a few shared assumptions:
If you are deploying to `https://<USERNAME>.github.io/`, you can omit `base` as it defaults to `"/"`.
If you are deploying to `https://<USERNAME>.github.io/<REPO>/`, (i.e. your repository is at `https://github.com/<USERNAME>/<REPO>`), set `base` to `"/<REPO>/"`.
If you are deploying to `https://<USERNAME>.github.io/<REPO>/`, (that is your repository is at `https://github.com/<USERNAME>/<REPO>`), set `base` to `"/<REPO>/"`.
2. Inside your project, create `deploy.sh` with the following content (with highlighted lines uncommented appropriately) and run it to deploy:
@@ -62,7 +62,7 @@ You can also run the above script in your CI setup to enable automatic deploymen
If you are deploying to `https://<USERNAME or GROUP>.github.io/`, you can omit `base` as it defaults to `"/"`.
If you are deploying to `https://<USERNAME or GROUP>.github.io/<REPO>/`, (i.e. your repository is at `https://github.com/<USERNAME>/<REPO>`), set `base` to `"/<REPO>/"`.
If you are deploying to `https://<USERNAME or GROUP>.github.io/<REPO>/`, (that is your repository is at `https://github.com/<USERNAME>/<REPO>`), set `base` to `"/<REPO>/"`.
2. Create a file named `.travis.yml` in the root of your project.
@@ -90,7 +90,7 @@ deploy:
If you are deploying to `https://<USERNAME or GROUP>.gitlab.io/`, you can omit `base` as it defaults to `"/"`.
If you are deploying to `https://<USERNAME or GROUP>.gitlab.io/<REPO>/`, (i.e. your repository is at `https://gitlab.com/<USERNAME>/<REPO>`), set `base` to `"/<REPO>/"`.
If you are deploying to `https://<USERNAME or GROUP>.gitlab.io/<REPO>/`, (that is your repository is at `https://gitlab.com/<USERNAME>/<REPO>`), set `base` to `"/<REPO>/"`.
2. Set `dest` in `.vuepress/config.js` to `public`.
@@ -153,7 +153,7 @@ pages:
## Surge
1. First install [surge](https://www.npmjs.com/package/surge), if you haven't already.
1. First install [surge](https://www.npmjs.com/package/surge), if you haven’t already.
2. Run `yarn docs:build` or `npm run docs:build`.
@@ -182,7 +182,7 @@ You can also deploy to a [custom domain](http://surge.sh/help/adding-a-custom-do
}
```
This is the configuration of your site. see more at [heroku-buildpack-static](https://github.com/heroku/heroku-buildpack-static).
This is the configuration of your site. See more at [heroku-buildpack-static](https://github.com/heroku/heroku-buildpack-static).
5. Set up your Heroku git remote:
@@ -211,4 +211,4 @@ heroku open
## Now
Please refer to [Deploy an example vuepress website with Now](https://zeit.co/examples/vuepress/).
Please check out [Deploy an example VuePress site with Now](https://zeit.co/examples/vuepress/).
packages/docs/docs/guide/directory-structure.md
+7 -3
View File
@@ -2,6 +2,8 @@
VuePress follows the principle of **"Convention is better than configuration"**, the recommended document structure is as follows:
<!-- textlint-disable terminology -->
::: vue
.
├── docs
@@ -27,11 +29,13 @@ VuePress follows the principle of **"Convention is better than configuration"**,
└── package.json
:::
<!-- textlint-enable -->
::: warning Note
Please note the capitalization of the directory name.
:::
- `docs/.vuepress`: It is used to store global configuration, components, static resources, etc.
- `docs/.vuepress`: It’s used to store global configuration, components, static resources, etc.
- `docs/.vuepress/components`: The Vue components in this directory will be automatically registered as global components.
- `docs/.vuepress/theme`: Used to store local theme.
- `docs/.vuepress/styles`: Stores style related files.
@@ -45,7 +49,7 @@ Please note the capitalization of the directory name.
- `docs/.vuepress/enhanceApp.js`: App level enhancement.
::: warning Note
When customizing `templates/ssr.html`, or `templates/dev.html`, it is best to modify it on the basis of the [default template files](https://github.com/vuejs/vuepress/blob/master/packages/%40vuepress/core/lib/client/index.dev.html), otherwise it may cause a build failure.
When customizing `templates/ssr.html`, or `templates/dev.html`, it’s best to edit it on the basis of the [default template files](https://github.com/vuejs/vuepress/blob/master/packages/%40vuepress/core/lib/client/index.dev.html), otherwise it may cause a build failure.
:::
## Default Page Routing
@@ -58,7 +62,7 @@ For the above directory structure, the default page routing paths are as follows
| `/guide/README.md` | `/guide/` |
| `/config.md` | `/config.html` |
**Also see:**
**Also see:**
- [Config](../config/README.md)
- [Theme](../theme/)
packages/docs/docs/guide/frontmatter.md
+7 -7
View File
@@ -1,6 +1,6 @@
# Front Matter
# Frontmatter
Any markdown file that contains a YAML front matter block will be processed by [gray-matter](https://github.com/jonschlinkert/gray-matter). The front matter must be the first thing in the markdown file and must take the form of valid YAML set between triple-dashed lines. Here is a basic example:
Any Markdown file that contains a YAML frontmatter block will be processed by [gray-matter](https://github.com/jonschlinkert/gray-matter). The frontmatter must be the first thing in the Markdown file and must take the form of valid YAML set between triple-dashed lines. Here is a basic example:
```markdown
---
@@ -12,14 +12,14 @@ lang: en-US
Between these triple-dashed lines, you can set predefined variables (see [below](#predefined-variables) for a reference), or even create custom ones of your own. These variables will then be available to you to access using <code>[$frontmatter](./global-computed.md#frontmatter)</code> at the rest of the page, plus all custom and theming components.
::: tip
Front matter variables are **optional** in VuePress.
frontmatter variables are **optional** in VuePress.
:::
## Alternative Front Matter Formats
## Alternative frontmatter Formats
In addition, VuePress also supports JSON or [TOML](https://github.com/toml-lang/toml) front matter.
VuePress also supports JSON or [TOML](https://github.com/toml-lang/toml) frontmatter.
JSON front matter needs to start and end in curly braces:
JSON frontmatter needs to start and end in curly braces:
```
---
@@ -30,7 +30,7 @@ JSON front matter needs to start and end in curly braces:
---
```
TOML front matter needs to be explicitly marked as TOML:
TOML frontmatter needs to be explicitly marked as TOML:
```
---toml
packages/docs/docs/guide/getting-started.md
+2 -2
View File
@@ -6,7 +6,7 @@ VuePress requires Node.js >= 8.
## Global Installation
If you just want to play around with VuePress, you can install it globally:
If you only want to play around with VuePress, you can install it globally:
``` bash
# install globally
@@ -37,7 +37,7 @@ echo '# Hello VuePress' > docs/README.md
```
::: warning
It is currently recommended to use [Yarn](https://yarnpkg.com/en/) instead of npm when installing VuePress into an existing project that has webpack 3.x as a dependency. Npm fails to generate the correct dependency tree in this case.
We currently recommend using [Yarn](https://yarnpkg.com/en/) instead of npm when installing VuePress into an existing project that has webpack 3.x as a dependency, because npm fails to generate the correct dependency tree in this case.
:::
Then, add some scripts to `package.json`:
packages/docs/docs/guide/global-computed.md
+3 -3
View File
@@ -1,10 +1,10 @@
# Global Computed
In VuePress, some core [computed](https://vuejs.org/v2/guide/computed.html#Computed-Properties) properties are built in for use by [default theme](../theme/default-theme-config.md) or custom themes.
In VuePress, some core [computed](https://vuejs.org/v2/guide/computed.html#Computed-Properties) properties are built-in for use by [default theme](../theme/default-theme-config.md) or custom themes.
## $site
This is the `$site` value of the website you see now:
This is the `$site` value of the site you see now:
``` json
{
@@ -80,4 +80,4 @@ The `content` value of the `<meta name= "description" content= "...">` for the c
## $themeConfig
i.e. `siteConfig.themeConfig`。
That is `siteConfig.themeConfig`。
packages/docs/docs/guide/i18n.md
+3 -3
View File
@@ -2,7 +2,7 @@
## Site Level i18n Config
To leverage multi-language support in VuePress, you first need to use the following file structure:
To take advantage of multi-language support in VuePress, you first need to use the following file structure:
```
docs
@@ -42,7 +42,7 @@ If a locale does not have `title` or `description` VuePress will fallback to the
## Default Theme i18n Config
The default theme also has built-in i18n support via `themeConfig.locales`, using the same `{ path: config }` format. Each locale can have its own [nav](../theme/default-theme-config.md#navbar-links) and [sidebar](../theme/default-theme-config.md#sidebar) config, in addition to a few other text values used across the site:
The default theme also has built-in i18n support via `themeConfig.locales`, using the same `{ path: config }` format. Each locale can have its own [nav](../theme/default-theme-config.md#navbar-links) and [sidebar](../theme/default-theme-config.md#sidebar) config, along with some other text values used across the site:
``` js
module.exports = {
@@ -56,7 +56,7 @@ module.exports = {
label: 'English',
// text for the edit-on-github link
editLinkText: 'Edit this page on GitHub',
// config for Service Worker
// config for Service Worker
serviceWorker: {
updatePopup: {
message: "New content is available.",
packages/docs/docs/guide/markdown-slot.md
+10 -6
View File
@@ -1,20 +1,20 @@
# Markdown Slot
VuePress implements a content distribution API for Markdown. With this feature, you can split your document into multiple fragments to facilitate flexible composition in the layout component.
VuePress implements a content distribution API for Markdown. With this feature, you can split your document into fragments, allowing flexible composition in the layout component.
## Why do I need Markdown Slot?
First, let's review the relationship between layout components and markdown files:
First, let’s review the relationship between layout components and Markdown files:
<diagram-markdown-slot-relationship/>
Markdown files are providers of metadata (Page content, Configuration, etc.), while layout components consume them. We can use `frontmatter` to define some metadata for common data types, but `frontmatter` is hard to do something about markdown / HTML, a complex metadata that involves differences before and after compilation.
Markdown files are providers of metadata (Page content, Configuration, etc.), while layout components consume them. We can use `frontmatter` to define some metadata for common data types, but `frontmatter` is hard to do something about Markdown / HTML, a complex metadata that involves differences before and after compilation.
Markdown Slot is to solve this kind of problem.
## Named Slots
You can define a named markdown slot through the following markdown syntax:
You can define a named Markdown slot through the following Markdown syntax:
``` md
::: slot name
@@ -34,7 +34,7 @@ Here we are using `slot-key` instead of `slot`, because in Vue, `slot` is a rese
## Default Slot Content
By default, the slot-free part of a markdown file becomes the default content of a markdown slot, which you can access directly using the `Content` component:
By default, the slot-free part of a Markdown file becomes the default content of a Markdown slot, which you can access directly using the `Content` component:
``` vue
<Content/>
@@ -60,7 +60,7 @@ Suppose your layout component is as follows:
</template>
```
If the markdown content of a page is like this:
If the Markdown content of a page is like this:
```md
::: slot header
@@ -100,6 +100,10 @@ Then the rendered HTML of this page will be:
</div>
```
<!-- textlint-disable en-capitalization -->
Note that:
1. Unlike the slot mechanism provided by [Vue](https://vuejs.org/v2/guide/components-slots.html) itself, each content distribution is wrapped in a `div` whose class is `content` with the name of the slot.
2. Please ensure the uniqueness of the slot defined.
<!-- textlint-enable -->
packages/docs/docs/guide/markdown.md
+9 -9
View File
@@ -8,7 +8,7 @@ Headers automatically get anchor links applied. Rendering of anchors can be conf
### Internal Links
Internal links are converted to `<router-link>` for SPA navigation. Also, every `README.md` or `index.md` contained in each sub-directory will automatically be converted to `index.html`, with corresponding url `/`.
Internal links are converted to `<router-link>` for SPA navigation. Also, every `README.md` or `index.md` contained in each sub-directory will automatically be converted to `index.html`, with corresponding URL `/`.
Given the following directory structure:
@@ -37,7 +37,7 @@ And providing you are in `foo/one.md`:
### Redirection for URLs <Badge text="1.0.0-alpha.37"/>
VuePress supports redirecting to clean links. If a link `/foo` is not found, VuePress will look for a existing `/foo/` or `/foo.html`. Conversely, when one of `/foo/` or `/foo.html` is not found, VuePress will also try the other. With this feature, we can customize your website's urls with the official plugin [vuepress-plugin-clean-urls](https://vuepress.github.io/plugins/clean-urls/).
VuePress supports redirecting to clean links. If a link `/foo` is not found, VuePress will look for a existing `/foo/` or `/foo.html`. Conversely, when one of `/foo/` or `/foo.html` is not found, VuePress will also try the other. With this feature, we can customize your website’s URLs with the official plugin [vuepress-plugin-clean-urls](https://vuepress.github.io/plugins/clean-urls/).
::: tip
Regardless of whether the permalink and clean-urls plugins are used, your relative path should be defined by the current file structure. In the above example, even though you set the path of `/foo/one.md` to `/foo/one/`, you should still access `/foo/two.md` via `./two.md`.
@@ -52,9 +52,9 @@ Outbound links automatically gets `target="_blank" rel="noopener noreferrer"`:
You can customize the attributes added to external links by setting [config.markdown.externalLinks](../config/README.md#markdown-externallinks).
## Front Matter
## Frontmatter
[YAML front matter](https://jekyllrb.com/docs/frontmatter/) is supported out of the box:
[YAML frontmatter](https://jekyllrb.com/docs/frontmatter/) is supported out of the box:
``` yaml
---
@@ -65,7 +65,7 @@ lang: en-US
This data will be available to the rest of the page, along with all custom and theming components.
For more details, check out the [Front Matter](./frontmatter.md) page.
For more details, check out the [Frontmatter](./frontmatter.md) page.
## GitHub-Style Tables
@@ -165,7 +165,7 @@ Danger zone, do not proceed
## Syntax Highlighting in Code Blocks
VuePress uses [Prism](https://prismjs.com/) to highlight language syntax in markdown code blocks, using coloured text. Prism supports a wide variety of programming languages. All you need to do is append a valid language alias to the beginning backticks for the code block:
VuePress uses [Prism](https://prismjs.com/) to highlight language syntax in Markdown code blocks, using coloured text. Prism supports a wide variety of programming languages. All you need to do is append a valid language alias to the beginning backticks for the code block:
**Input**
@@ -215,7 +215,7 @@ export default {
</ul>
```
Check out [the list of valid languages](https://prismjs.com/#languages-list) on the Prism website.
Check out [the list of valid languages](https://prismjs.com/#languages-list) on the Prism site.
## Line Highlighting in Code Blocks
@@ -314,13 +314,13 @@ It also supports [line highlighting](#line-highlighting-in-code-blocks):
<<< @/../@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()`.
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()`.
:::
## Advanced Configuration
VuePress uses [markdown-it](https://github.com/markdown-it/markdown-it) as the markdown renderer. A lot of the extensions above are implemented via custom plugins. You can further customize the `markdown-it` instance using the `markdown` option in `.vuepress/config.js`:
VuePress uses [markdown-it](https://github.com/markdown-it/markdown-it) as the Markdown renderer. A lot of the extensions above are implemented via custom plugins. You can further customize the `markdown-it` instance using the `markdown` option in `.vuepress/config.js`:
``` js
module.exports = {
packages/docs/docs/guide/permalinks.md
+5 -5
View File
@@ -2,7 +2,7 @@
## Background
Before 1.x.x, VuePress retrieves all markdown files in the documents source directory and defines the page links based on the file hierarchy. e.g. if you have the following file structure:
Before 1.x.x, VuePress retrieves all Markdown files in the documents source directory and defines the page links based on the file hierarchy. For example if you have the following file structure:
```
├── package.json
@@ -21,7 +21,7 @@ Then you will get following available pages:
/source/_post/intro-vuepress.html
```
However, for a blog system, we hope that the link of a post can be customized. VuePress started supporting this feature from `1.0.0`. which is known as `permalink`. Then, the actual pages would be:
Yet, for a blog system, we hope that the link of a post can be customized. VuePress started supporting this feature, known as permalink, from `1.0.0`. Then, the actual pages would be:
```
/source/
@@ -29,11 +29,11 @@ However, for a blog system, we hope that the link of a post can be customized. V
/source/2018/4/1/intro-vuepress.html
```
It seems that we have seen the shadow of the blog. Let's continue to look down.
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 many years into the future, yielding a hyperlink that is less susceptible to link root<sup>[1]</sup>. VuePress supports a flexible way to build permalinks, allowing you to leverage various 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<sup>[1]</sup>. VuePress supports a flexible way to build permalinks, allowing you to use template variables.
The default permalink is `/:regular`.
@@ -48,7 +48,7 @@ module.exports = {
}
```
Alternatively, you can also set permalink on a page only, and it will have a higher priority than the global settings.
You can also set permalink on a page only, and it will have a higher priority than the global settings.
📝 __hello.md__:
packages/docs/docs/guide/using-vue.md
+14 -14
View File
@@ -12,7 +12,7 @@ If you are using or demoing components that are not SSR friendly (for example co
</ClientOnly>
```
Note this does not fix components or libraries that access Browser APIs **on import** - in order to use code that assumes a browser environment on import, you need to dynamically import them in proper lifecycle hooks:
Note this does not fix components or libraries that access Browser APIs **on import** - to use code that assumes a browser environment on import, you need to dynamically import them in proper lifecycle hooks:
``` vue
<script>
@@ -30,7 +30,7 @@ export default {
### Interpolation
Each markdown file is first compiled into HTML and then passed on as a Vue component to `vue-loader`. This means you can use Vue-style interpolation in text:
Each Markdown file is first compiled into HTML and then passed on as a Vue component to `vue-loader`. This means you can use Vue-style interpolation in text:
**Input**
@@ -78,7 +78,7 @@ The compiled component does not have any private data but does have access to th
## Escaping
By default, fenced code blocks are automatically wrapped with `v-pre`. If you want to display raw mustaches or Vue-specific syntax inside inline code snippets or plain text, you need to wrap a paragraph with the `v-pre` custom container:
By default, fenced code blocks are automatically wrapped with `v-pre`. To display raw mustaches or Vue-specific syntax inside inline code snippets or plain text, you need to wrap a paragraph with the `v-pre` custom container:
**Input**
@@ -108,7 +108,7 @@ Any `*.vue` files found in `.vuepress/components` are automatically registered a
        └─ Bar.vue
```
Inside any markdown file you can then directly use the components (names are inferred from filenames):
Inside any Markdown file you can then directly use the components (names are inferred from filenames):
``` md
<demo-1/>
@@ -123,14 +123,14 @@ Inside any markdown file you can then directly use the components (names are inf
<Foo-Bar/>
::: warning IMPORTANT
Make sure a custom component's name either contains a hyphen or is in PascalCase. Otherwise it will be treated as an inline element and wrapped inside a `<p>` tag, which will lead to hydration mismatch because `<p>` does not allow block elements to be placed inside it.
Make sure a custom component’s name either contains a hyphen or is in PascalCase. Otherwise it will be treated as an inline element and wrapped inside a `<p>` tag, which will lead to hydration mismatch because `<p>` does not allow block elements to be placed inside it.
:::
### Using Components In Headers
You can use Vue components in the headers, but note the difference between the following two ways:
| markdown | Output HTML | Parsed Header |
| Markdown | Output HTML | Parsed Header |
|--------|-------------|----------------|
| <pre v-pre><code> # text &lt;Tag/&gt; </code></pre> | `<h1>text <Tag/></h1>` | `text` |
| <pre v-pre><code> # text \`&lt;Tag/&gt;\` </code></pre> | `<h1>text <code>&lt;Tag/&gt;</code></h1>` | `text <Tag/>` |
@@ -150,7 +150,7 @@ VuePress has built-in webpack config for the following pre-processors: `sass`, `
yarn add -D sass-loader node-sass
```
Now you can use the following in markdown and theme components:
Now you can use the following in Markdown and theme components:
``` vue
<style lang="sass">
@@ -166,14 +166,14 @@ yarn add -D pug pug-plain-loader
```
::: tip
If you are a Stylus user, you don't need to install `stylus` and `stylus-loader` in your project because VuePress uses Stylus internally.
If you are a Stylus user, you don’t need to install `stylus` and `stylus-loader` in your project because VuePress uses Stylus internally.
For pre-processors that do not have built-in webpack config support, you will need to [extend the internal webpack config](../config/README.md#configurewebpack) in addition to installing the necessary dependencies.
For pre-processors that do not have built-in webpack config support, you will need to [extend the internal webpack config](../config/README.md#configurewebpack) and install the necessary dependencies.
:::
## Script & Style Hoisting
Sometimes you may need to apply some JavaScript or CSS only to the current page. In those cases, you can directly write root-level `<script>` or `<style>` blocks in the markdown file, and they will be hoisted out of the compiled HTML and used as the `<script>` and `<style>` blocks for the resulting Vue single-file component.
Sometimes you may need to apply some JavaScript or CSS only to the current page. In those cases, you can directly write root-level `<script>` or `<style>` blocks in the Markdown file, and they will be hoisted out of the compiled HTML and used as the `<script>` and `<style>` blocks for the resulting Vue single-file component.
<p class="demo" :class="$style.example"></p>
@@ -197,7 +197,7 @@ export default {
### OutboundLink <Badge text="stable"/>
It(<OutboundLink/>) is used to indicate that this is an external link. In VuePress, this component has been followed by every external link.
It(<OutboundLink/>) is used to specify that this is an external link. In VuePress, this component has been followed by every external link.
### ClientOnly <Badge text="stable"/>
@@ -207,12 +207,12 @@ See [Browser API Access Restrictions](#browser-api-access-restrictions).
- **Props**:
- `pageKey` - string, [page](./global-computed.md#page)'s hash key, defaults to current page's key.
- `slotKey` - string, key of [markdown slot](./markdown-slot.md). defaults to [default slot](./markdown-slot.md#default-slot-content).
- `pageKey` - string, [page](./global-computed.md#page)'s hash key, defaults to current page’s key.
- `slotKey` - string, key of [Markdown slot](./markdown-slot.md). Defaults to [default slot](./markdown-slot.md#default-slot-content).
- **Usage**：
Specify a specific slot for a specific page (.md) for rendering. This will be very useful when you use [Custom Layout](../theme/default-theme-config.md#custom-layout-for-specific-pages) or [Writing a theme](../theme/writing-a-theme.md)
Specify a specific slot for a specific page (.md) for rendering. This will be useful when you use [Custom Layout](../theme/default-theme-config.md#custom-layout-for-specific-pages) or [Writing a theme](../theme/writing-a-theme.md)
``` vue
<Content/>
packages/docs/docs/miscellaneous/design-concepts.md
+18 -14
View File
@@ -12,11 +12,11 @@ The design concepts of VuePress 1.x are mainly reflected in the following aspect
## Pluggable
VuePress 1.0 has been rewritten extensively, and the most important one is the introduction of the [Plugin API](../plugin/README.md). So what're the benefits of plugins?
VuePress 1.0 has been rewritten extensively, and the most important one is the introduction of the [Plugin API](../plugin/README.md). What are the benefits of plugins?
### Decoupling
With plugins, we can implement many of the core functions with plugins, and you can see many built-in plugins [here](https://github.com/vuejs/vuepress/tree/master/packages/%40vuepress/core/lib/node/internal-plugins) that cover many of the core functions of VuePress, which used to blend in all parts of the code base, but now they're clear at a glance.
With plugins, we can implement many of the core functions with plugins, and you can see many built-in plugins [here](https://github.com/vuejs/vuepress/tree/master/packages/%40vuepress/core/lib/node/internal-plugins) that cover many of the core functions of VuePress, which used to blend in all parts of the code base, but now they’re clear at a glance.
### Configuration management
@@ -78,9 +78,9 @@ module.exports = {
## Convention over configuration.
VuePress 1.0 begin to introduce some conventions to reduce the user's excessive configuration pressure, the most intuitive manifestation of this is the conventions for the [document directory structure](../guide/directory-structure.md) and the [theme directory structure](../theme/writing-a-theme.md#directory-structure).
VuePress 1.0 begin to introduce some conventions to reduce the user’s excessive configuration pressure, the most intuitive manifestation of this is the conventions for the [document directory structure](../guide/directory-structure.md) and the [theme directory structure](../theme/writing-a-theme.md#directory-structure).
In the future, we may combine community feedback to introduce more agreements. Let's wait and see.
In the future, we may combine community feedback to introduce more agreements. Let’s wait and see.
## Reasonable priority management.
@@ -90,13 +90,15 @@ Senior users have found that both theme developers and regular users have the ab
For `templates/*`, follow the certain loading priority. Taking `templates/ssr.html` as an example:
<!-- textlint-disable en-capitalization, terminology -->
@flowstart
cond1=>condition: User's ssr.html
cond1=>condition: User’s ssr.html
exists?
cond2=>condition: Theme's ssr.html
cond2=>condition: Theme’s ssr.html
exists?
stage1=>operation: Using user's ssr.html
stage2=>operation: Using theme's ssr.html
stage1=>operation: Using user’s ssr.html
stage2=>operation: Using theme’s ssr.html
stage3=>operation: Using default ssr.html
cond1(no, right)->cond2(no)->stage3
@@ -104,8 +106,10 @@ cond1(yes, bottom)->stage1
cond2(yes, bottom)->stage2
@flowend
<!-- textlint-enable -->
::: warning Note
When customizing `templates/ssr.html`, or `templates/dev.html`, it is best to modify it on the basis of the [default template files](https://github.com/vuejs/vuepress/blob/master/packages/%40vuepress/core/lib/app/index.dev.html), otherwise it may cause a build failure.
When customizing `templates/ssr.html`, or `templates/dev.html`, it’s best to edit it on the basis of the [default template files](https://github.com/vuejs/vuepress/blob/master/packages/%40vuepress/core/lib/app/index.dev.html), otherwise it may cause a build failure.
:::
### Overriding
@@ -114,7 +118,7 @@ For `palette.styl`, `index.styl` and `plugins`, follow the principles of overrid
#### palette.styl
User's `styles/palette.styl` has a higher priority than the theme's `styles/palette.styl`, so the theme can define its own palette and the user can tweak it. e.g.
User’s `styles/palette.styl` has a higher priority than the theme’s `styles/palette.styl`, so the theme can define its own palette and the user can tweak it. For example:
```stylus
// theme/styles/palette.styl
@@ -130,7 +134,7 @@ So the final value of `$accentColor` is `#f00`.
#### index.styl
Both the user's `styles/index.styl` and the theme's `styles/index.styl` are generated into the final `CSS` file, but the user's style is generated later and therefore has higher priority. e.g.
Both the user’s `styles/index.styl` and the theme’s `styles/index.styl` are generated into the final `CSS` file, but the user’s style is generated later and therefore has higher priority. For example:
```stylus
// theme/styles/index.styl
@@ -160,7 +164,7 @@ The final generated CSS is as follows:
#### plugins
Since all plugins with the same name can be applied ONLY once by default, users can override the default options for plugins in theme. e.g.
Since all plugins with the same name can be applied ONLY once by default, users can override the default options for plugins in theme. For example:
```js
// theme/index.js
@@ -178,7 +182,7 @@ module.exports = {
plugins: [
'vuepress-plugin-xxx',
{ name: 'bar' }
]
]
}
```
@@ -192,6 +196,6 @@ With the goal of decoupling, we were able to separate VuePress into the followin
- [@vuepress/core](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/core)：Including the core implementation of `dev`, `build` and `Plugin API`;
- [@vuepress/theme-default](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/theme-default)：The default theme you see now.
Of course, for most users, you don't need to care about these three libraries, package [vuepress](https://www.npmjs.com/search?Q=vuepress) has already assembled them together, so you can use VuePress like `0.x`.
Of course, for most users, you don’t need to worry about these three libraries. The [VuePress](https://www.npmjs.com/search?Q=vuepress) package has already assembled them together, so you can use VuePress like `0.x`.
packages/docs/docs/miscellaneous/glossary.md
+6 -6
View File
@@ -4,7 +4,7 @@ sidebar: auto
# Glossary
You may encounter some unfamiliar concepts in the documentation. This section lists the common terms in the documentation for easy access, learning and plugin/theme development.
You may stumble upon some unfamiliar concepts in the documentation. This section lists the common terms in the documentation for easy access, learning and plugin/theme development.
## layout
@@ -16,7 +16,7 @@ Name of the layout component used by the current page.
- Access: `$page.frontmatter`
Configuration wrapped by `---` in the `markdown` file of the current page, which is generally used to do some page-level configuration. For more details, please see [Front Matter](../guide/frontmatter.md).
Configuration wrapped by `---` in the `markdown` file of the current page, generally used to do some page-level configuration. For more details, please see [Frontmatter](../guide/frontmatter.md).
## permalink
@@ -31,7 +31,7 @@ Permalinks. For more details, please head [permalinks](../guide/permalinks.md).
The current page is based on the URL generated by the directory structure.
::: tip
When dynamically generating routes during the build period, a page's URL (`$page.path`) will use `$page.frontmatter.permalink` first, and if it doesn't exist, it will be downgraded to `$page.regularPath`.
When dynamically generating routes during the build period, a page’s URL (`$page.path`) will use `$page.frontmatter.permalink` first, and if it doesn’t exist, it will be downgraded to `$page.regularPath`.
:::
## headers
@@ -50,19 +50,19 @@ That is, those titles defined by one or more `#` in `markdown`.
- Access: `$themeConfig | Context.themeConfig`
Value of `themeConfig` in `.vuepress/config.js`, i.e., user's theme configuration.
Value of `themeConfig` in `.vuepress/config.js`, i.e., user’s theme configuration.
## themePath
- Access: `Context.themeAPI.theme.path`
Root path (absolute path) of the currently used theme.
Root path (absolute path) of the used theme.
## themeEntry
- Access: `Context.themeAPI.theme.entry`
Theme's configuration file - `themePath/index.js`.
Theme’s configuration file - `themePath/index.js`.
## parentThemePath
packages/docs/docs/plugin/README.md
+6 -6
View File
@@ -1,13 +1,13 @@
# Plugin
Plugins usually add global-level functionality to VuePress. There is no strictly defined scope for a plugin - there are typically several types of plugins:
Plugins generally add global-level functionality to VuePress. There is no strictly defined scope for a plugin - there are typically several types of plugins:
1. Extend the page's metadata generated at compile time. e.g. [@vuepress/plugin-last-updated](./official/plugin-last-updated.md);
2. Generate extra files before or after compilation. e.g. [@vuepress/plugin-pwa](./official/plugin-pwa.md);
3. Inject global UI. e.g. [@vuepress/plugin-back-to-top](./official/plugin-back-to-top.md);
4. Extend the CLI with custom commands. e.g. [vuepress-plugin-export](https://github.com/ulivz/vuepress-plugin-export).
1. Extend the page’s metadata generated at compile time. For example [@vuepress/plugin-last-updated](./official/plugin-last-updated.md);
2. Generate extra files before or after compilation. For example [@vuepress/plugin-pwa](./official/plugin-pwa.md);
3. Inject global UI. For example [@vuepress/plugin-back-to-top](./official/plugin-back-to-top.md);
4. Extend the CLI with custom commands. For example [vuepress-plugin-export](https://github.com/ulivz/vuepress-plugin-export).
Here is also a litte slightly complicated plugin example [@vuepress/plugin-blog](https://vuepress-plugin-blog.ulivz.com). that uses compile-time metadata to generate some dynamic modules and initialize them on the client side by using `enhanceAppFiles`.
Here is also a litte slightly complicated plugin example [@vuepress/plugin-blog](https://vuepress-plugin-blog.ulivz.com) that uses compile-time metadata to generate some dynamic modules and initialize them on the client-side by using `enhanceAppFiles`.
The architecture of the whole plugin system is as follows:
packages/docs/docs/plugin/life-cycle.md
+1 -1
View File
@@ -1,4 +1,4 @@
# Life Cycle
# Lifecycle
## ready
packages/docs/docs/plugin/option-api.md
+17 -17
View File
@@ -7,7 +7,7 @@
The name of the plugin.
Internally, vuepress will use the plugin's package name as the plugin name. When your plugin is a local plugin (i.e. using a pure plugin function directly), please be sure to configure this option, that is good for debug tracking.
Internally, VuePress will use the plugin’s package name as the plugin name. When your plugin is a local plugin (that is using a pure plugin function directly), please be sure to configure this option, that is good for debug tracking.
```js
// .vuepress/config.js
@@ -28,7 +28,7 @@ module.exports = {
- Type: `array`
- Default: `undefined`
A plugin can contain multiple plugins like a preset.
A plugin can contain several plugins like a preset.
```js
// A plugin
@@ -45,7 +45,7 @@ module.exports = {
- Type: `Function`
- Default: undefined
Modify the internal webpack config with [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain).
Edit the internal webpack config with [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain).
```js
module.exports = {
@@ -56,7 +56,7 @@ module.exports = {
```
::: tip
Since VuePress is a Vue-SSR based application, there will be two webpack configurations, `isServer` is used to determine whether the current webpack config is applied to the server or client.
Since VuePress is a Vue-SSR based application, there needs to be two webpack configurations, `isServer` is used to determine whether the current webpack config is applied to the server or client.
**Also see:**
@@ -82,7 +82,7 @@ module.exports = {
}
```
VuePress specifically opened up a more concise `define` option, note that the values has been automatically processed by `JSON.stringify`.
VuePress opened up a more concise `define` option, note that the values has been automatically processed by `JSON.stringify`.
- Object Usage:
@@ -137,7 +137,7 @@ module.exports = (options, context) => ({
- Type: `Function`
- Default: undefined
Equivalent to [before](https://webpack.js.org/configuration/dev-server/#devserver-before) in [webpack-dev-server](https://github.com/webpack/webpack-dev-server). you can use it to define custom handlers before all middleware is executed:
Equivalent to [before](https://webpack.js.org/configuration/dev-server/#devserver-before) in [webpack-dev-server](https://github.com/webpack/webpack-dev-server). You can use it to define custom handlers before all middleware is executed:
```js
module.exports = {
@@ -155,7 +155,7 @@ module.exports = {
- Type: `Function`
- Default: undefined
Equivalent to [after](https://webpack.js.org/configuration/dev-server/#devserver-after) in [webpack-dev-server](https://github.com/webpack/webpack-dev-server). you can use it to execute custom middleware after all other middleware:
Equivalent to [after](https://webpack.js.org/configuration/dev-server/#devserver-after) in [webpack-dev-server](https://github.com/webpack/webpack-dev-server). You can use it to execute custom middleware after all other middleware:
```js
module.exports = {
@@ -171,7 +171,7 @@ module.exports = {
- Type: `Function`
- Default: `undefined`
A function to modify default config or apply additional plugins to the [markdown-it](https://github.com/markdown-it/markdown-it) instance used to render source files. Example:
A function to edit default config or apply extra plugins to the [markdown-it](https://github.com/markdown-it/markdown-it) instance used to render source files. Example:
```js
module.exports = {
@@ -187,7 +187,7 @@ module.exports = {
- Type: `Function`
- Default: `undefined`
Modify the internal markdown config with [markdown-it-chain](https://github.com/ulivz/markdown-it-chain) —— A chaining API like [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain) but for [markdown-it](https://github.com/markdown-it/markdown-it).
Edit the internal Markdown config with [markdown-it-chain](https://github.com/ulivz/markdown-it-chain) —— A chaining API like [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain) but for [markdown-it](https://github.com/markdown-it/markdown-it).
```js
module.exports = {
@@ -237,7 +237,7 @@ module.exports = {
}
```
This option also supports dynamic code which allows you to do more things with the ability to touch the compilation context:
This option also supports dynamic code which allows you to do more, with the ability to touch the compilation context:
```js
module.exports = (option, context) => {
@@ -272,7 +272,7 @@ module.exports = (options, context) => ({
})
```
Then you can use this module at client side code by:
Then you can use this module at client-side code by:
``` js
import { SOURCE_DIR } from '@dynamic/constants'
@@ -283,7 +283,7 @@ import { SOURCE_DIR } from '@dynamic/constants'
- Type: `Function`
- Default: `undefined`
A function used to extend or modify the [$page](../guide/global-computed.md#page) object. This function will be invoking once for each page at compile time.
A function used to extend or edit the [$page](../guide/global-computed.md#page) object. This function will be invoking once for each page at compile time.
```js
module.exports = {
@@ -312,7 +312,7 @@ module.exports = {
These fields starting with an `_` means you can only access them during build time.
:::
e.g.
For example:
``` js
module.exports = {
@@ -329,7 +329,7 @@ Then you can use this value via `this.$page.size` in any Vue component.
- Type: `String`
- Default: `undefined`
A path to the mixin file which allow you to control the life cycle of root component.
A path to the mixin file which allows you to control the lifecycle of root component.
``` js
// plugin's entry
@@ -353,7 +353,7 @@ export default {
- Type: `Array|AsyncFunction`
- Default: `undefined`
Add a page pointing to a markdown file:
Add a page pointing to a Markdown file:
```js
const path = require('path')
@@ -407,7 +407,7 @@ module.exports = {
- Type: `Array|String`
- Default: `undefined`
You might want to inject some global UI fixed somewhere on the page, e.g. `back-to-top`, `popup`. In VuePress, **a global UI is a Vue component**, you can directly define the component's name(s) in this option, e.g.
You might want to inject some global UI fixed somewhere on the page, for example `back-to-top`, `popup`. In VuePress, **a global UI is a Vue component**, you can directly define the component’s name(s) in this option, for example:
``` js
module.exports = {
@@ -435,7 +435,7 @@ Then, VuePress will automatically inject these components behind the layout comp
- Type: `function`
- Default: `undefined`
Register a extra command to enhance the CLI of vuepress. The function will be called with a [CAC](https://github.com/cacjs/cac)'s instance as the first argument.
Register a extra command to enhance the CLI of VuePress. The function will be called with a [CAC](https://github.com/cacjs/cac)'s instance as the first argument.
```js
module.exports = {
packages/docs/docs/plugin/using-a-plugin.md
+2 -2
View File
@@ -12,7 +12,7 @@ module.exports = {
## Use plugins from a dependency
A plugin can be published on npm in `CommonJS` format as `vuepress-plugin-xxx`. you can use it:
A plugin can be published on npm in `CommonJS` format as `vuepress-plugin-xxx`. You can use it:
``` js
module.exports = {
@@ -75,7 +75,7 @@ module.exports = {
}
```
Since this style is consistent with [babel's Plugin/Preset Options](https://babeljs.io/docs/en/plugins#plugin-preset-options), we call it `Babel Style`.
Since this style is consistent with [babel’s Plugin/Preset Options](https://babeljs.io/docs/en/plugins#plugin-preset-options), we call it `Babel Style`.
### Object Style
packages/docs/docs/plugin/writing-a-plugin.md
+2 -2
View File
@@ -1,6 +1,6 @@
# Writing a Plugin
A plugin should export a `plain JavaScript object`(`#1`). If the plugin needs to take options, it can be a function that returns a plain object(`#2`). The function will be called with the plugin's options as the first argument, along with [ctx](./context-api.md) which provides some compile-time metadata.
A plugin should export a `plain JavaScript object`(`#1`). If the plugin needs to take options, it can be a function that returns a plain object(`#2`). The function will be called with the plugin’s options as the first argument, along with [ctx](./context-api.md) which provides some compile-time metadata.
``` js
// #1
@@ -19,5 +19,5 @@ module.exports = (options, ctx) => {
```
::: tip
A VuePress plugin module should be a `CommonJS Module` because VuePress plugins runs on the Node side.
A VuePress plugin module should be a `CommonJS Module` because VuePress plugins runs on the Node.js side.
:::
packages/docs/docs/theme/README.md
Vendored
+1 -1
View File
@@ -1,5 +1,5 @@
# Theme
::: tip
Theme components are subject to the same [browser API access restrictions](../guide/using-vue.md#browser-api-access-restrictions).
Theme components are under the same [browser API access restrictions](../guide/using-vue.md#browser-api-access-restrictions).
:::
packages/docs/docs/theme/default-theme-config.md
Vendored
+19 -19
View File
@@ -8,7 +8,7 @@ All options listed on this page apply to the default theme only. If you are usin
## Homepage
The default theme provides a homepage layout (which is used on [the homepage of this very website](../README.md)). To use it, specify `home: true` plus some other metadata in your root `README.md`'s [YAML front matter](../guide/markdown.md#front-matter). This is an example of how it works:
The default theme provides a homepage layout (used on [the homepage of this site](../README.md)). To use it, specify `home: true` plus some other metadata in your root `README.md`'s [YAML frontmatter](../guide/markdown.md#front-matter). This is an example of how it works:
``` yaml
---
@@ -29,13 +29,13 @@ footer: MIT Licensed | Copyright © 2018-present Evan You
---
```
Any additional content after the `YAML front matter` will be parsed as normal markdown and rendered after the features section.
Any extra content after the `YAML front matter` will be parsed as normal Markdown and rendered after the features section.
If you want to use a completely custom homepage layout, you can also use a [Custom Layout](#custom-layout-for-specific-pages).
To use a fully custom homepage layout, you can also use a [Custom Layout](#custom-layout-for-specific-pages).
## Navbar
The Navbar may contain your page title, [Search Box](#search-box), [Navbar Links](#navbar-links), [Languages](../guide/i18n.md) and [Repository Link](#git-repo-and-edit-links), all of them depends on your configuration.
The Navbar may contain your page title, [Search Box](#search-box), [Navbar Links](#navbar-links), [Languages](../guide/i18n.md) and [Repository Link](#git-repo-and-edit-links), they all depend on your configuration.
### Navbar Links
@@ -72,7 +72,7 @@ module.exports = {
}
```
In addition, you can have sub groups inside a dropdown by having nested items:
You can also have sub groups inside a dropdown by having nested items:
```js
module.exports = {
@@ -128,7 +128,7 @@ module.exports = {
}
```
You can omit the `.md` extension, and paths ending with `/` are inferred as `*/README.md`. The text for the link is automatically inferred (either from the first header in the page or explicit title in `YAML front matter`). If you wish to explicitly specify the link text, use an Array in form of `[link, text]`.
You can omit the `.md` extension, and paths ending with `/` are inferred as `*/README.md`. The text for the link is automatically inferred (either from the first header in the page or explicit title in `YAML front matter`). To explicitly specify the link text, use an array in form of `[link, text]`.
### Nested Header Links
@@ -167,12 +167,12 @@ module.exports = {
```
::: tip
It is worth mentioning that when you disable this option, the corresponding script of this functionality will not be loaded. This is a small point in our performance optimization.
It’s worth mentioning that when you disable this option, the corresponding script of this functionality will not be loaded. This is a small point in our performance optimization.
:::
### Sidebar Groups
You can divide sidebar links into multiple groups by using objects:
You can divide sidebar links into several groups by using objects:
``` js
// .vuepress/config.js
@@ -207,7 +207,7 @@ A sidebar group config also supports [sidebarDepth](#nested-header-links) field
### Multiple Sidebars
If you wish to display different sidebars for different sections of content, first organize your pages into directories for each desired section:
To display different sidebars for different sections of content, first organize your pages into directories for each desired section:
```
.
@@ -262,7 +262,7 @@ VuePress checks each sidebar config from top to bottom. If the fallback configur
### Auto Sidebar for Single Pages
If you wish to automatically generate a sidebar that contains only the header links for the current page, you can use `YAML front matter` on that page:
To automatically generate a sidebar that contains only the header links for the current page, you can use `YAML front matter` on that page:
``` yaml
---
@@ -346,14 +346,14 @@ module.exports = {
```
::: warning Note
Unlike the [built-in search](#built-in-search) engine which works out of the box, [Algolia DocSearch](https://community.algolia.com/docsearch/) requires you to submit your site to them for indexing before it starts working.
Unlike the [built-in search](#built-in-search) engine which works out of the box, [Algolia DocSearch](https://community.algolia.com/docsearch/) requires you to submit your site to them for indexing before it starts working.
:::
For more options, refer to [Algolia DocSearch's documentation](https://github.com/algolia/docsearch#docsearch-options).
For more options, check out [Algolia DocSearch’s documentation](https://github.com/algolia/docsearch#docsearch-options).
## Last Updated
The `themeConfig.lastUpdated` option allows you to get the UNIX timestamp(ms) of each file's last `git` commit, and it will also display at the bottom of each page in an appropriate format:
The `themeConfig.lastUpdated` option allows you to get the UNIX timestamp(ms) of each file’s last `git` commit, and it will also display at the bottom of each page in an appropriate format:
``` js
module.exports = {
@@ -363,10 +363,10 @@ module.exports = {
}
```
Note that it's `off` by default. If given a `string`, it will be displayed as a prefix (default value: `Last Updated`).
Note that it’s `off` by default. If given a `string`, it will be displayed as a prefix (default value: `Last Updated`).
::: warning
Since `lastUpdated` is based on `git`, you can only use it in a `git` repository. Also, since the timestamp used comes from the git commit, it will display only after a first commit for a given page, and update only on subsequent commits of that page.
Since `lastUpdated` is based on `git`, you can only use it in a `git` repository. Also, since the timestamp used comes from the git commit, it will display only after a first commit for a given page, and update only on ensuing commits of that page.
:::
@@ -385,7 +385,7 @@ next: false
---
```
## Git Repo and Edit Links
## Git repository and Edit Links
Providing `themeConfig.repo` auto generates a GitHub link in the navbar and "Edit this page" links at the bottom of each page.
@@ -448,7 +448,7 @@ These styles are written in [index.styl](/config/#index-styl), a file that allow
## Custom Layout for Specific Pages
By default the content of each `*.md` file is rendered in a `<div class="page">` container, along with the sidebar, auto-generated edit links and prev/next links. If you wish to use a completely custom component in place of the page, you can again specify the component to use using `YAML front matter`:
By default the content of each `*.md` file is rendered in a `<div class="page">` container, along with the sidebar, auto-generated edit links and prev/next links. To use a fully custom component in place of the page, you can again specify the component to use using `YAML front matter`:
``` yaml
---
@@ -460,8 +460,8 @@ This will render `.vuepress/components/SpecialLayout.vue` for the given page.
## Ejecting
You can copy the default theme source code into `.vuepress/theme` to fully customize the theme using the `vuepress eject [targetDir]` command.
You can copy the default theme source code into `.vuepress/theme` to fully customize the theme using the `vuepress eject [targetDir]` command.
::: warning
Once you eject, you are on your own and **won't** be receiving future updates or bug fixes to the default theme even if you upgrade VuePress.
Once you eject, you are on your own and **won’t** be receiving future updates or bugfixes to the default theme even if you upgrade VuePress.
:::
packages/docs/docs/theme/inheritance.md
Vendored
+27 -23
View File
@@ -4,28 +4,28 @@
We have two main reasons to support this feature:
1. VuePress provides users with a [default theme](./default-theme-config.md), which meets the needs of document writers in most scenarios, even so, there are still many users who choose to `eject` and modify it, even if they may only need to make minor changes to one of the components.
1. VuePress provides users with a [default theme](./default-theme-config.md), which meets the needs of document writers in most scenarios, even so, there are still many users who choose to `eject` and edit it, even if they may only need to make minor changes to one of the components.
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. In addition, 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.
Therefore, we need to provide a reasonable and reliable theme inheritance strategy.
Consequently, we need to provide a reasonable and reliable theme inheritance strategy.
## Concepts
To introduce this section, let's start with a few basic concepts:
To introduce this section, let’s start with some basic concepts:
- **Atomic theme**：i.e. the parent theme, which is implemented entirely from scratch, like the default theme.
- **Derived theme**：i.e. the child theme, which is created based on parent theme.
- **Atomic theme**：that is the parent theme, implemented entirely from scratch, like the default theme.
- **Derived theme**：that is the child theme, created based on parent theme.
::: tip
For now theme inheritance doesn't support high-order inheritance, that means, a derived theme cannot be inherited.
For now theme inheritance doesn’t support high-order inheritance, that means, a derived theme cannot be inherited.
:::
## Usage
Suppose you want to create a theme inherited from the default theme, you just need to configure the [extend](./option-api.md#extend) option in your theme configuration:
Suppose you want to create a theme inherited from the default theme, you only need to configure the [extend](./option-api.md#extend) option in your theme configuration:
```js
module.exports = {
@@ -39,11 +39,11 @@ All the capabilities of the parent theme will be `"passed"` to the child theme.
The [file-level conventions](./writing-a-theme.md#directory-structure) are as follows:
- **Global Components**，i.e. the Vue components under `theme/global-components`.
- **Components**，i.e. the Vue components under `theme/components`.
- **Global Style and Palette**，i.e. `index.styl` and `palette.styl` under `theme/styles`.
- **HTML Template**，i.e. `dev.html` and `ssr.html` under `theme/templates`.
- **Theme-Level App Enhancement File**，i.e. `theme/enhanceApp.js`
- **Global Components**，that is the Vue components under `theme/global-components`.
- **Components**，that is the Vue components under `theme/components`.
- **Global Style and Palette**，that is `index.styl` and `palette.styl` under `theme/styles`.
- **HTML Template**, that is `dev.html` and `ssr.html` under `theme/templates`.
- **Theme-Level App Enhancement File**，that is `theme/enhanceApp.js`
For theme configuration, the configuration options that can be overrode by child theme are as follows:
@@ -76,7 +76,7 @@ module.exports = {
}
```
The child theme can modify the options of plugin in the following ways:
The child theme can edit the options of plugin in the following ways:
```js
// themePath/index.js
@@ -101,12 +101,12 @@ module.exports = {
```
::: warning
Normally, you don't need to do this unless you know clearly that disabling plugins in parent themes won't cause problems.
You shouldn’t need to do this unless you know for sure that disabling plugins in parent themes won’t cause problems.
:::
## Override Components
You may want to override the same-name components in the parent theme. By default, when the components in the parent theme use relative paths to reference other components, you will not be able to do this because you cannot modify the code of the parent theme at runtime.
You may want to override the same-name components in the parent theme. By default, when the components in the parent theme use relative paths to reference other components, you will not be able to do this because you cannot edit the code of the parent theme at runtime.
VuePress achieves this requirement in a clever way, but there is a requirement for the parent theme - **All components must use the `@theme` alias to refer to other components**.
@@ -140,20 +140,24 @@ On this premise, when you create a `Navbar` component in the same place in the c
theme
└── components
   └── `Navbar.vue`
:::
:::
`@theme/components/Navbar.vue` will automatically map to the Navbar component in the child theme. and when you remove the component, `@theme/components/Navbar.vue` will automatically restore to the Navbar component in the parent theme.
`@theme/components/Navbar.vue` will automatically map to the Navbar component in the child theme, and when you remove the component, `@theme/components/Navbar.vue` will automatically restore to the Navbar component in the parent theme.
In this way, you can easily "tamper" with some part of an atomic theme.
This way, you can "tamper" with some part of an atomic theme.
<!-- textlint-disable en-capitalization -->
::: tip
1. You'd better override the component based on the code of the corresponding component in the parent theme.
2. Currently, when developing theme locally, you need to manually restart dev server when a component is created or removed.
1. You’d better override the component based on the code of the corresponding component in the parent theme.
2. When developing theme locally, you need to manually restart the dev server when a component is created or removed.
:::
<!-- textlint-enable -->
## Access Parent Theme
You can use `@parent-theme` to access the root path of the parent theme. The following example shows creating a layout component with the same name in a child theme and simply using slots in the parent theme. [@vuepress/theme-vue](https://github.com/vuejs/vuepress/tree/master/packages/%40vuepress/theme-vue) is created in this way.
You can use `@parent-theme` to access the root path of the parent theme. The following example shows creating a layout component with the same name in a child theme and using slots in the parent theme. [@vuepress/theme-vue](https://github.com/vuejs/vuepress/tree/master/packages/%40vuepress/theme-vue) is created in this way.
```vue
<!-- themePath/components/Foo.vue -->
packages/docs/docs/theme/option-api.md
Vendored
+5 -5
View File
@@ -24,9 +24,9 @@ module.exports = (themeConfig, ctx) => {
::: tip
1. You should see the difference between `themeEntry` and `themeConfig`, the former is a configuration for the theme itself, which is provided by VuePress. the latter is the user's configuration for the theme, which is implemented by the currently used theme, e.g. [Default Theme Config](./default-theme-config.md).
1. You should see the difference between `themeEntry` and `themeConfig`, the former is a configuration for the theme itself, provided by VuePress. The latter is the user’s configuration for the theme, implemented by the used theme, for example [Default Theme Config](./default-theme-config.md).
2. In addition to the options listed in this section, `themeEntry` also supports all [Option API](../plugin/option-api.md) and [Life Cycle](../plugin/life-cycle.md) supported by plugins.
2. Along with the options listed in this section, `themeEntry` also supports all [Option API](../plugin/option-api.md) and [Lifecycle](../plugin/life-cycle.md) supported by plugins.
:::
## plugins
@@ -41,7 +41,7 @@ module.exports = (themeConfig, ctx) => {
---
::: warning
You probably don't need to use following options tagged with <Badge text="Danger Zone" vertical="middle"/> unless you know what you are doing!
You probably don’t need to use following options tagged with <Badge text="Danger Zone" vertical="middle"/> unless you know what you are doing!
:::
## devTemplate <Badge text="Danger Zone"/>
@@ -73,7 +73,7 @@ module.exports = {
}
```
VuePress provides the ability to inherit one theme from another. VuePress will follow the concept of `override` and automatically help you prioritize various thematic attributes, e.g. styles and layout components.
VuePress provides the ability to inherit one theme from another. VuePress will follow the concept of `override` and automatically help you prioritize thematic attributes, for example styles and layout components.
**Also see:**
@@ -95,7 +95,7 @@ module.exports = {
Global layout component is a component responsible for the global layout strategy. The [default global layout](https://github.com/vuejs/vuepress/blob/master/packages/%40vuepress/core/lib/app/components/GlobalLayout.vue) will help you render different layouts according to [$frontmatter.layout](../guide/frontmatter.md#layout), so in most cases you do not need to configure this option.
For example, when you want to set a global header and footer for your theme, you can do this:
```vue
<!-- themePath/layouts/GlobalLayout.vue -->
<template>
packages/docs/docs/theme/writing-a-theme.md
Vendored
+16 -16
View File
@@ -9,11 +9,11 @@ To write a theme, create a `.vuepress/theme` directory in your docs root, and th
   └─ Layout.vue
:::
From there it's the same as developing a normal Vue application. It is entirely up to you how to organize your theme.
From there it’s the same as developing a normal Vue application. It’s entirely up to you how to organize your theme.
## Content Outlet
The compiled content of the current `.md` file being rendered will be available as a special `<Content/>` global component. You will need to render it somewhere in your layout in order to display the content of the page. The simplest theme can be just a single `Layout.vue` component with the following content:
The compiled content of the current `.md` file being rendered will be available as a special `<Content/>` global component. You will need to render it somewhere in your layout to display the content of the page. The simplest theme can be a single `Layout.vue` component with the following content:
``` html
<template>
@@ -29,9 +29,9 @@ The compiled content of the current `.md` file being rendered will be available
## Directory Structure
Just one `Layout.vue` might not be enough, and you might also want to define more layout components in the theme for using on different pages. You may also want to customize the [palette](../config/README.md#palette-styl), and even apply some plugins.
One `Layout.vue` might not be enough, and you might also want to define more layout components in the theme for using on different pages. You may also want to customize the [palette](../config/README.md#palette-styl), and even apply some plugins.
So it's time to reorganize your theme, an agreed theme directory structure is as follows:
So it’s time to reorganize your theme, an agreed theme directory structure is as follows:
::: vue
theme
@@ -53,16 +53,16 @@ theme
└── package.json
:::
- `theme/global-components`: Components under this directory will be automatically registered as global components. For details, please refer to [@vuepress/plugin-register-components](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/plugin-register-components).
- `theme/global-components`: Components under this directory will be automatically registered as global components. For details, please check out [@vuepress/plugin-register-components](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/plugin-register-components).
- `theme/components`: Your components.
- `theme/layouts`: Layout components of the theme, where `Layout.vue` is required.
- `theme/styles`: Global style and palette.
- `theme/templates`: Modify default template.
- `theme/templates`: Edit default template.
- `theme/index.js`: Entry file of theme configuration.
- `theme/enhanceApp.js`: Theme level enhancements.
::: warning Note
When you publish your theme as an NPM package, if you don't have any theme configuration, that means you don't have `theme/index.js`, you'll need to set the `"main"` field to `layouts/Layout.vue` in `package.json`, only in this way VuePress can correctly resolve the theme.
When you publish your theme as an npm package, if you don’t have any theme configuration, that means you don’t have `theme/index.js`, you’ll need to set the `"main"` field to `layouts/Layout.vue` in `package.json`, only in this way VuePress can properly resolve the theme.
```json
{
...
@@ -87,7 +87,7 @@ theme
Then, all the pages will use `Layout.vue` as layout component by default, while the routes not matching will use `404.vue`.
If you want to switch the layout of some pages to `AnotherLayout.vue`, you just need to update the frontmatter of this page:
To switch the layout of some pages to `AnotherLayout.vue`, all you have to do is update the frontmatter of this page:
```markdown
---
@@ -96,7 +96,7 @@ layout: AnotherLayout
````
::: tip
Each layout component may render distinct pages. If you want to apply some global UI (e.g. global header), consider using [globalLayout](./option-api.md#globallayout)。
Each layout component may render distinct pages. To apply some global UI (for example global header), consider using [globalLayout](./option-api.md#globallayout)。
:::
## Apply plugins
@@ -106,7 +106,7 @@ You can apply some plugins to the theme via `theme/index.js`.
```js
module.exports = {
plugins: [
['@vuepress/pwa', {
['@vuepress/pwa', {
serviceWorker: true,
updatePopup: true
}]
@@ -118,7 +118,7 @@ module.exports = {
The `Layout` component will be invoked once for every `.md` file in `docs`, and the metadata for the entire site and that specific page will be exposed respectively as `this.$site` and `this.$page` properties which are injected into every component in the app.
This is the value of `$site` of this very website:
This is the value of `$site` of this website:
``` json
{
@@ -137,7 +137,7 @@ This is the value of `$site` of this very website:
}
```
`title`, `description` and `base` are copied from respective fields in `.vuepress/config.js`. `pages` contains an array of metadata objects for each page, including its path, page title (explicitly specified in [YAML front matter](../guide/markdown.md#front-matter) or inferred from the first header on the page), and any YAML front matter data in that file.
`title`, `description` and `base` are copied from respective fields in `.vuepress/config.js`. `pages` contains an array of metadata objects for each page, including its path, page title (explicitly specified in [YAML frontmatter](../guide/markdown.md#front-matter) or inferred from the first header on the page), and any YAML frontmatter data in that file.
This is the `$page` object for this page you are looking at:
@@ -153,19 +153,19 @@ This is the `$page` object for this page you are looking at:
If the user provided `themeConfig` in `.vuepress/config.js`, it will also be available as `$site.themeConfig`. You can use this to allow users to customize behavior of your theme - for example, specifying categories and page order. You can then use these data together with `$site.pages` to dynamically construct navigation links.
Finally, don't forget that `this.$route` and `this.$router` are also available as part of Vue Router's API.
Don’t forget that `this.$route` and `this.$router` are also available as part of Vue Router’s API.
::: tip
`lastUpdated` is the UNIX timestamp of this file's last git commit, for more details, refer to [Last Updated](../theme/default-theme-config.md#last-updated).
`lastUpdated` is the UNIX timestamp of this file’s last git commit, for more details, check out [Last Updated](../theme/default-theme-config.md#last-updated).
:::
## Content Excerpt
If a markdown file contains a `<!-- more -->` comment, any content above the comment will be extracted and exposed as `$page.excerpt`. If you are building custom theme for blogging, this data can be used to render a post list with excerpts.
If a Markdown file contains a `<!-- more -->` comment, any content above the comment will be extracted and exposed as `$page.excerpt`. If you are building custom theme for blogging, this data can be used to render a post list with excerpts.
## App Level Enhancements
Themes can enhance the Vue app that VuePress uses by exposing an `enhanceApp.js` file at the root of the theme. The file should `export default` a hook function which will receive an object containing some app-level values. You can use this hook to install additional Vue plugins, register global components, or add additional router hooks:
Themes can enhance the Vue app that VuePress uses by exposing an `enhanceApp.js` file at the root of the theme. The file should `export default` a hook function which will receive an object containing some app-level values. You can use this hook to install more Vue plugins, register global components, or add router hooks:
``` js
export default ({
packages/docs/package.json
+14 -1
View File
@@ -4,10 +4,12 @@
"name": "docs",
"description": "docs of VuePress",
"scripts": {
"precommit": "lint-staged",
"dev": "vuepress dev docs --temp .temp",
"build": "vuepress build docs --temp .temp",
"view-info": "vuepress view-info docs --temp .temp",
"show-help": "vuepress --help"
"show-help": "vuepress --help",
"lint-md": "textlint ./docs/**/*.md"
},
"repository": {
"type": "git",
@@ -25,11 +27,22 @@
},
"homepage": "https://github.com/vuejs/vuepress#readme",
"devDependencies": {
"@textlint-rule/textlint-rule-no-unmatched-pair": "^1.0.7",
"@vuepress/plugin-back-to-top": "^1.0.3",
"@vuepress/plugin-google-analytics": "^1.0.3",
"@vuepress/plugin-medium-zoom": "^1.0.3",
"@vuepress/plugin-pwa": "^1.0.3",
"@vuepress/theme-vue": "^1.0.3",
"lint-staged": "^8.1.5",
"textlint": "^11.3.1",
"textlint-filter-rule-comments": "^1.2.2",
"textlint-rule-apostrophe": "^1.0.0",
"textlint-rule-common-misspellings": "^1.0.1",
"textlint-rule-diacritics": "^1.0.0",
"textlint-rule-en-capitalization": "^2.0.2",
"textlint-rule-stop-words": "^1.0.17",
"textlint-rule-terminology": "^1.1.30",
"textlint-rule-write-good": "^1.6.2",
"vue-toasted": "^1.1.25",
"vuepress": "^1.0.3",
"vuepress-plugin-flowchart": "^1.4.2"
yarn.lock
+924 -18
View File
File diff suppressed because it is too large Load Diff