From 8039f421f7525852daf2dc5787c19fea19659242 Mon Sep 17 00:00:00 2001 From: Sarah Dayan Date: Wed, 7 Aug 2019 17:24:58 +0200 Subject: [PATCH] docs: documentation linting (#1745) * 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 --- .lintstagedrc | 3 + package.json | 21 +- packages/docs/.lintstagedrc | 3 + packages/docs/.textlint.terms.json | 8 + packages/docs/.textlintrc.js | 23 + packages/docs/docs/api/cli.md | 4 +- packages/docs/docs/api/node.md | 8 +- packages/docs/docs/config/README.md | 42 +- packages/docs/docs/faq/README.md | 22 +- packages/docs/docs/guide/README.md | 18 +- packages/docs/docs/guide/assets.md | 14 +- packages/docs/docs/guide/basic-config.md | 12 +- packages/docs/docs/guide/deploy.md | 14 +- .../docs/docs/guide/directory-structure.md | 10 +- packages/docs/docs/guide/frontmatter.md | 14 +- packages/docs/docs/guide/getting-started.md | 4 +- packages/docs/docs/guide/global-computed.md | 6 +- packages/docs/docs/guide/i18n.md | 6 +- packages/docs/docs/guide/markdown-slot.md | 16 +- packages/docs/docs/guide/markdown.md | 18 +- packages/docs/docs/guide/permalinks.md | 10 +- packages/docs/docs/guide/using-vue.md | 28 +- .../docs/miscellaneous/design-concepts.md | 32 +- packages/docs/docs/miscellaneous/glossary.md | 12 +- packages/docs/docs/plugin/README.md | 12 +- packages/docs/docs/plugin/life-cycle.md | 2 +- packages/docs/docs/plugin/option-api.md | 34 +- packages/docs/docs/plugin/using-a-plugin.md | 4 +- packages/docs/docs/plugin/writing-a-plugin.md | 4 +- packages/docs/docs/theme/README.md | 2 +- .../docs/docs/theme/default-theme-config.md | 38 +- packages/docs/docs/theme/inheritance.md | 50 +- packages/docs/docs/theme/option-api.md | 10 +- packages/docs/docs/theme/writing-a-theme.md | 32 +- packages/docs/package.json | 15 +- yarn.lock | 942 +++++++++++++++++- 36 files changed, 1232 insertions(+), 261 deletions(-) create mode 100644 .lintstagedrc create mode 100644 packages/docs/.lintstagedrc create mode 100644 packages/docs/.textlint.terms.json create mode 100644 packages/docs/.textlintrc.js diff --git a/.lintstagedrc b/.lintstagedrc new file mode 100644 index 0000000000..693feae125 --- /dev/null +++ b/.lintstagedrc @@ -0,0 +1,3 @@ +{ + "*.{js,vue}": ["eslint --fix", "git add"] +} diff --git a/package.json b/package.json index 148676f6cd..7224ad641b 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/packages/docs/.lintstagedrc b/packages/docs/.lintstagedrc new file mode 100644 index 0000000000..0dbeb548bd --- /dev/null +++ b/packages/docs/.lintstagedrc @@ -0,0 +1,3 @@ +{ + "docs/**/*.md": ["yarn lint-md", "git add"] +} diff --git a/packages/docs/.textlint.terms.json b/packages/docs/.textlint.terms.json new file mode 100644 index 0000000000..7ea8ecd744 --- /dev/null +++ b/packages/docs/.textlint.terms.json @@ -0,0 +1,8 @@ +[ + "Stylus", + "VuePress", + [ + "front[- ]matter", + "frontmatter" + ] +] diff --git a/packages/docs/.textlintrc.js b/packages/docs/.textlintrc.js new file mode 100644 index 0000000000..068b522bc2 --- /dev/null +++ b/packages/docs/.textlintrc.js @@ -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 + } +} diff --git a/packages/docs/docs/api/cli.md b/packages/docs/docs/api/cli.md index 32bb29c2c2..54cbff90cf 100644 --- a/packages/docs/docs/api/cli.md +++ b/packages/docs/docs/api/cli.md @@ -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 diff --git a/packages/docs/docs/api/node.md b/packages/docs/docs/api/node.md index 0e712b7d34..55db476a6a 100644 --- a/packages/docs/docs/api/node.md +++ b/packages/docs/docs/api/node.md @@ -14,7 +14,7 @@ Create a VuePress application. #### App.prototype.process: () => Promise\ | 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\ | never @@ -27,7 +27,7 @@ Launch a build process with current app context. ### dev(\[options]): Promise\ -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\ -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). diff --git a/packages/docs/docs/config/README.md b/packages/docs/docs/config/README.md index 96ea75e639..ebdcb8f2aa 100644 --- a/packages/docs/docs/config/README.md +++ b/packages/docs/docs/config/README.md @@ -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 `` tag in the page HTML. +Description for the site. This will render as a `` tag in the page HTML. ### head - Type: `Array` - Default: `[]` -Extra tags to be injected to the page HTML ``. 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 ``. 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 `` 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 `` 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 = { diff --git a/packages/docs/docs/faq/README.md b/packages/docs/docs/faq/README.md index e705149060..3bbec4e28b 100644 --- a/packages/docs/docs/faq/README.md +++ b/packages/docs/docs/faq/README.md @@ -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
-## 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`. diff --git a/packages/docs/docs/guide/README.md b/packages/docs/docs/guide/README.md index d8eabdd99a..023e509561 100644 --- a/packages/docs/docs/guide/README.md +++ b/packages/docs/docs/guide/README.md @@ -2,21 +2,21 @@ -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. diff --git a/packages/docs/docs/guide/assets.md b/packages/docs/docs/guide/assets.md index 77af2b62b4..f2fa605350 100644 --- a/packages/docs/docs/guide/assets.md +++ b/packages/docs/docs/guide/assets.md @@ -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 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. diff --git a/packages/docs/docs/guide/basic-config.md b/packages/docs/docs/guide/basic-config.md index 5a17dbcd01..5e72fffd62 100644 --- a/packages/docs/docs/guide/basic-config.md +++ b/packages/docs/docs/guide/basic-config.md @@ -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 ({ diff --git a/packages/docs/docs/guide/deploy.md b/packages/docs/docs/guide/deploy.md index 0ba55dbbf1..ae81f8a18c 100644 --- a/packages/docs/docs/guide/deploy.md +++ b/packages/docs/docs/guide/deploy.md @@ -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://.github.io/`, you can omit `base` as it defaults to `"/"`. - If you are deploying to `https://.github.io//`, (i.e. your repository is at `https://github.com//`), set `base` to `"//"`. + If you are deploying to `https://.github.io//`, (that is your repository is at `https://github.com//`), set `base` to `"//"`. 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://.github.io/`, you can omit `base` as it defaults to `"/"`. - If you are deploying to `https://.github.io//`, (i.e. your repository is at `https://github.com//`), set `base` to `"//"`. + If you are deploying to `https://.github.io//`, (that is your repository is at `https://github.com//`), set `base` to `"//"`. 2. Create a file named `.travis.yml` in the root of your project. @@ -90,7 +90,7 @@ deploy: If you are deploying to `https://.gitlab.io/`, you can omit `base` as it defaults to `"/"`. - If you are deploying to `https://.gitlab.io//`, (i.e. your repository is at `https://gitlab.com//`), set `base` to `"//"`. + If you are deploying to `https://.gitlab.io//`, (that is your repository is at `https://gitlab.com//`), set `base` to `"//"`. 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/). diff --git a/packages/docs/docs/guide/directory-structure.md b/packages/docs/docs/guide/directory-structure.md index cf66608712..091f82ea77 100644 --- a/packages/docs/docs/guide/directory-structure.md +++ b/packages/docs/docs/guide/directory-structure.md @@ -2,6 +2,8 @@ VuePress follows the principle of **"Convention is better than configuration"**, the recommended document structure is as follows: + + ::: vue . ├── docs @@ -27,11 +29,13 @@ VuePress follows the principle of **"Convention is better than configuration"**, └── package.json ::: + + ::: 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/) diff --git a/packages/docs/docs/guide/frontmatter.md b/packages/docs/docs/guide/frontmatter.md index c4b4273e66..d45882496f 100644 --- a/packages/docs/docs/guide/frontmatter.md +++ b/packages/docs/docs/guide/frontmatter.md @@ -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 [$frontmatter](./global-computed.md#frontmatter) 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 diff --git a/packages/docs/docs/guide/getting-started.md b/packages/docs/docs/guide/getting-started.md index 321cdf87d3..3fda7e1044 100644 --- a/packages/docs/docs/guide/getting-started.md +++ b/packages/docs/docs/guide/getting-started.md @@ -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`: diff --git a/packages/docs/docs/guide/global-computed.md b/packages/docs/docs/guide/global-computed.md index b64922a7ee..dcb1bb5705 100644 --- a/packages/docs/docs/guide/global-computed.md +++ b/packages/docs/docs/guide/global-computed.md @@ -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 `` for the c ## $themeConfig -i.e. `siteConfig.themeConfig`。 +That is `siteConfig.themeConfig`。 diff --git a/packages/docs/docs/guide/i18n.md b/packages/docs/docs/guide/i18n.md index 5dbe742180..12dc65465b 100644 --- a/packages/docs/docs/guide/i18n.md +++ b/packages/docs/docs/guide/i18n.md @@ -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.", diff --git a/packages/docs/docs/guide/markdown-slot.md b/packages/docs/docs/guide/markdown-slot.md index ca6399c141..fc65d14206 100644 --- a/packages/docs/docs/guide/markdown-slot.md +++ b/packages/docs/docs/guide/markdown-slot.md @@ -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: -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 @@ -60,7 +60,7 @@ Suppose your layout component is as follows: ``` -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: ``` + + 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. + + diff --git a/packages/docs/docs/guide/markdown.md b/packages/docs/docs/guide/markdown.md index b844515fbf..c9bde4f91e 100644 --- a/packages/docs/docs/guide/markdown.md +++ b/packages/docs/docs/guide/markdown.md @@ -8,7 +8,7 @@ Headers automatically get anchor links applied. Rendering of anchors can be conf ### Internal Links -Internal links are converted to `` 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 `` 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 -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 { ``` -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 = { diff --git a/packages/docs/docs/guide/permalinks.md b/packages/docs/docs/guide/permalinks.md index 9399e2920f..0069a6c7ea 100644 --- a/packages/docs/docs/guide/permalinks.md +++ b/packages/docs/docs/guide/permalinks.md @@ -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[1]. 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[1]. 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__: diff --git a/packages/docs/docs/guide/using-vue.md b/packages/docs/docs/guide/using-vue.md index f5628b6a3a..d982641abd 100644 --- a/packages/docs/docs/guide/using-vue.md +++ b/packages/docs/docs/guide/using-vue.md @@ -12,7 +12,7 @@ If you are using or demoing components that are not SSR friendly (for example co ``` -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