diff --git a/docs/.vuepress/config.ts b/docs/.vuepress/config.ts index e7a50801..4bf273ce 100644 --- a/docs/.vuepress/config.ts +++ b/docs/.vuepress/config.ts @@ -5,7 +5,6 @@ import { webpackBundler } from '@vuepress/bundler-webpack' import { docsearchPlugin } from '@vuepress/plugin-docsearch' import { registerComponentsPlugin } from '@vuepress/plugin-register-components' import { defineUserConfig } from 'vuepress' -import type { UserConfig } from 'vuepress' import { getDirname, path } from 'vuepress/utils' import { head } from './configs/index.js' import theme from './theme.js' @@ -117,4 +116,4 @@ export default defineUserConfig({ componentsDir: path.resolve(__dirname, './components'), }), ], -}) as UserConfig +}) diff --git a/docs/.vuepress/configs/navbar/en.ts b/docs/.vuepress/configs/navbar/en.ts index db2d725c..35d4034d 100644 --- a/docs/.vuepress/configs/navbar/en.ts +++ b/docs/.vuepress/configs/navbar/en.ts @@ -18,6 +18,7 @@ export const enNavbar = navbar([ '/guide/plugin.md', '/guide/bundler.md', '/guide/migration.md', + '/guide/troubleshooting.md', ], }, { @@ -47,61 +48,9 @@ export const enNavbar = navbar([ prefix: 'bundler/', children: ['vite', 'webpack'], }, - { - text: 'Default Theme', - prefix: 'default-theme/', - children: [ - 'config', - 'frontmatter', - 'components', - 'markdown', - 'styles', - 'extending', - ], - }, - ], - }, - { - text: 'Plugins', - icon: 'fa6-solid:plug', - prefix: '/reference/plugin/', - children: [ - { - text: 'Common Features', - children: [ - 'back-to-top', - 'container', - 'external-link-icon', - 'google-analytics', - 'medium-zoom', - 'nprogress', - 'register-components', - ], - }, - { - text: 'Content Search', - children: ['docsearch', 'search'], - }, - { - text: 'PWA', - children: ['pwa', 'pwa-popup'], - }, - { - text: 'Syntax Highlighting', - children: ['prismjs', 'shiki'], - }, - { - text: 'Theme Development', - children: [ - 'active-header-links', - 'git', - 'palette', - 'theme-data', - 'toc', - ], - }, ], }, + { text: 'Learn More', icon: 'fa6-solid:feather', @@ -122,6 +71,14 @@ export const enNavbar = navbar([ { text: 'Resources', children: [ + { + text: 'Official Ecosystem', + link: 'https://ecosystem.vuejs.press/', + }, + { + text: 'VuePress MarketPlace', + link: 'https://marketplace.vuejs.press', + }, { text: 'Contributing Guide', link: 'https://github.com/vuepress/core/blob/main/CONTRIBUTING.md', @@ -130,10 +87,6 @@ export const enNavbar = navbar([ text: 'Awesome VuePress', link: 'https://github.com/vuepress/awesome-vuepress', }, - { - text: 'VuePress MarketPlace', - link: 'https://marketplace.vuejs.press', - }, ], }, ], diff --git a/docs/.vuepress/configs/navbar/zh.ts b/docs/.vuepress/configs/navbar/zh.ts index 16f1f038..845d3140 100644 --- a/docs/.vuepress/configs/navbar/zh.ts +++ b/docs/.vuepress/configs/navbar/zh.ts @@ -18,6 +18,7 @@ export const zhNavbar = navbar([ '/zh/guide/plugin.md', '/zh/guide/bundler.md', '/zh/guide/migration.md', + '/zh/guide/troubleshooting.md', ], }, { @@ -43,59 +44,6 @@ export const zhNavbar = navbar([ prefix: 'bundler/', children: ['vite', 'webpack'], }, - { - text: '默认主题', - prefix: 'default-theme/', - children: [ - 'config', - 'frontmatter', - 'components', - 'markdown', - 'styles', - 'extending', - ], - }, - ], - }, - { - text: '插件', - icon: 'fa6-solid:plug', - prefix: '/zh/reference/plugin/', - children: [ - { - text: '常用功能', - children: [ - 'back-to-top', - 'container', - 'external-link-icon', - 'google-analytics', - 'medium-zoom', - 'nprogress', - 'register-components', - ], - }, - { - text: '内容搜索', - children: ['docsearch', 'search'], - }, - { - text: 'PWA', - children: ['pwa', 'pwa-popup'], - }, - { - text: '语法高亮', - children: ['prismjs', 'shiki'], - }, - { - text: '主题开发', - children: [ - 'active-header-links', - 'git', - 'palette', - 'theme-data', - 'toc', - ], - }, ], }, { @@ -118,6 +66,14 @@ export const zhNavbar = navbar([ { text: '其他资源', children: [ + { + text: '官方生态系统', + link: 'https://ecosystem.vuejs.press/zh/', + }, + { + text: 'VuePress 市场', + link: 'https://marketplace.vuejs.press/zh/', + }, { text: '贡献指南', link: 'https://github.com/vuepress/core/blob/main/CONTRIBUTING_zh.md', @@ -126,10 +82,6 @@ export const zhNavbar = navbar([ text: 'Awesome VuePress', link: 'https://github.com/vuepress/awesome-vuepress', }, - { - text: 'VuePress 市场', - link: 'https://marketplace.vuejs.press/zh/', - }, ], }, ], diff --git a/docs/.vuepress/configs/sidebar/en.ts b/docs/.vuepress/configs/sidebar/en.ts index 1ae27d7f..f5cd7c15 100644 --- a/docs/.vuepress/configs/sidebar/en.ts +++ b/docs/.vuepress/configs/sidebar/en.ts @@ -2,18 +2,24 @@ import { sidebar } from 'vuepress-theme-hope' export const enSidebar = sidebar({ '/guide/': [ - 'introduction', - 'getting-started', - 'configuration', - 'page', - 'markdown', - 'assets', - 'i18n', - 'deployment', - 'theme', - 'plugin', - 'bundler', - 'migration', + { + text: 'Guide', + children: [ + '/guide/introduction.md', + '/guide/getting-started.md', + '/guide/configuration.md', + '/guide/page.md', + '/guide/markdown.md', + '/guide/assets.md', + '/guide/i18n.md', + '/guide/deployment.md', + '/guide/theme.md', + '/guide/plugin.md', + '/guide/bundler.md', + '/guide/migration.md', + '/guide/troubleshooting.md', + ], + }, ], '/advanced/': [ { @@ -60,56 +66,61 @@ export const enSidebar = sidebar({ }, { text: 'Default Theme Reference', - icon: 'fa6-solid:palette', - prefix: 'default-theme/', collapsible: true, children: [ - 'config', - 'frontmatter', - 'components', - 'markdown', - 'styles', - 'extending', + '/reference/default-theme/config.md', + '/reference/default-theme/frontmatter.md', + '/reference/default-theme/components.md', + '/reference/default-theme/markdown.md', + '/reference/default-theme/styles.md', + '/reference/default-theme/extending.md', ], }, { text: 'Official Plugins Reference', - icon: 'fa6-solid:plug', - prefix: 'plugin/', collapsible: true, children: [ { text: 'Common Features', children: [ - 'back-to-top', - 'container', - 'external-link-icon', - 'google-analytics', - 'medium-zoom', - 'nprogress', - 'register-components', + '/reference/plugin/back-to-top.md', + '/reference/plugin/container.md', + '/reference/plugin/external-link-icon.md', + '/reference/plugin/google-analytics.md', + '/reference/plugin/medium-zoom.md', + '/reference/plugin/nprogress.md', + '/reference/plugin/register-components.md', ], }, { text: 'Content Search', - children: ['docsearch', 'search'], + children: [ + '/reference/plugin/docsearch.md', + '/reference/plugin/search.md', + ], }, { text: 'PWA', - children: ['pwa', 'pwa-popup'], + children: [ + '/reference/plugin/pwa.md', + '/reference/plugin/pwa-popup.md', + ], }, { text: 'Syntax Highlighting', - children: ['prismjs', 'shiki'], + children: [ + '/reference/plugin/prismjs.md', + '/reference/plugin/shiki.md', + ], }, { text: 'Theme Development', children: [ - 'active-header-links', - 'git', - 'palette', - 'theme-data', - 'toc', + '/reference/plugin/active-header-links.md', + '/reference/plugin/git.md', + '/reference/plugin/palette.md', + '/reference/plugin/theme-data.md', + '/reference/plugin/toc.md', ], }, ], diff --git a/docs/.vuepress/configs/sidebar/zh.ts b/docs/.vuepress/configs/sidebar/zh.ts index fcfe38cc..04ee5162 100644 --- a/docs/.vuepress/configs/sidebar/zh.ts +++ b/docs/.vuepress/configs/sidebar/zh.ts @@ -2,18 +2,24 @@ import { sidebar } from 'vuepress-theme-hope' export const zhSidebar = sidebar({ '/zh/guide/': [ - 'introduction', - 'getting-started', - 'configuration', - 'page', - 'markdown', - 'assets', - 'i18n', - 'deployment', - 'theme', - 'plugin', - 'bundler', - 'migration', + { + text: '指南', + children: [ + '/zh/guide/introduction.md', + '/zh/guide/getting-started.md', + '/zh/guide/configuration.md', + '/zh/guide/page.md', + '/zh/guide/markdown.md', + '/zh/guide/assets.md', + '/zh/guide/i18n.md', + '/zh/guide/deployment.md', + '/zh/guide/theme.md', + '/zh/guide/plugin.md', + '/zh/guide/bundler.md', + '/zh/guide/migration.md', + '/zh/guide/troubleshooting.md', + ], + }, ], '/zh/advanced/': [ { @@ -60,56 +66,61 @@ export const zhSidebar = sidebar({ }, { text: '默认主题参考', - icon: 'fa6-solid:palette', - prefix: 'default-theme/', collapsible: true, children: [ - 'config', - 'frontmatter', - 'components', - 'markdown', - 'styles', - 'extending', + '/zh/reference/default-theme/config.md', + '/zh/reference/default-theme/frontmatter.md', + '/zh/reference/default-theme/components.md', + '/zh/reference/default-theme/markdown.md', + '/zh/reference/default-theme/styles.md', + '/zh/reference/default-theme/extending.md', ], }, { text: '官方插件参考', - icon: 'fa6-solid:plug', collapsible: true, - prefix: 'plugin/', children: [ { text: '常用功能', children: [ - 'back-to-top', - 'container', - 'external-link-icon', - 'google-analytics', - 'medium-zoom', - 'nprogress', - 'register-components', + '/zh/reference/plugin/back-to-top.md', + '/zh/reference/plugin/container.md', + '/zh/reference/plugin/external-link-icon.md', + '/zh/reference/plugin/google-analytics.md', + '/zh/reference/plugin/medium-zoom.md', + '/zh/reference/plugin/nprogress.md', + '/zh/reference/plugin/register-components.md', ], }, { text: '内容搜索', - children: ['docsearch', 'search'], + children: [ + '/zh/reference/plugin/docsearch.md', + '/zh/reference/plugin/search.md', + ], }, { text: 'PWA', - children: ['pwa', 'pwa-popup'], + children: [ + '/zh/reference/plugin/pwa.md', + '/zh/reference/plugin/pwa-popup.md', + ], }, { text: '语法高亮', - children: ['prismjs', 'shiki'], + children: [ + '/zh/reference/plugin/prismjs.md', + '/zh/reference/plugin/shiki.md', + ], }, { text: '主题开发', children: [ - 'active-header-links', - 'git', - 'palette', - 'theme-data', - 'toc', + '/zh/reference/plugin/active-header-links.md', + '/zh/reference/plugin/git.md', + '/zh/reference/plugin/palette.md', + '/zh/reference/plugin/theme-data.md', + '/zh/reference/plugin/toc.md', ], }, ], diff --git a/docs/advanced/cookbook/making-a-theme-extendable.md b/docs/advanced/cookbook/making-a-theme-extendable.md index bf919f55..6159309a 100644 --- a/docs/advanced/cookbook/making-a-theme-extendable.md +++ b/docs/advanced/cookbook/making-a-theme-extendable.md @@ -8,7 +8,7 @@ Sometimes users might want make some minor changes to a theme, but they don't wa With the help of [Theme API](../../reference/theme-api.md), you can make your theme extendable, allowing users to make their own modifications easily. -You must have known that how to [extend default theme](../../reference/default-theme/extending.md). Here we'll introduce how to make your own theme extendable like default theme. +You must have known that how to [extend default theme](https://ecosystem.vuejs.press/themes/default/extending.html). Here we'll introduce how to make your own theme extendable like default theme. ## Layout Slots diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md index 83b6a790..680f55d5 100644 --- a/docs/guide/configuration.md +++ b/docs/guide/configuration.md @@ -21,7 +21,7 @@ To be more specific, we have a convention for config file paths (in order of pre You can also specify the config file via `--config` option of [CLI](../reference/cli.md): -```sh +```bash vuepress dev docs --config my-config.ts ``` diff --git a/docs/guide/i18n.md b/docs/guide/i18n.md index 8cdc221c..0be695cd 100644 --- a/docs/guide/i18n.md +++ b/docs/guide/i18n.md @@ -73,5 +73,5 @@ export default defineUserConfig({ ``` ::: tip -Config reference: [Default Theme > locales](../reference/default-theme/config.md#locales) +Config reference: [Default Theme > locales](https://ecosystem.vuejs.press/themes/default/config.html#locales) ::: diff --git a/docs/guide/markdown.md b/docs/guide/markdown.md index 9888f5f3..359fb0c1 100644 --- a/docs/guide/markdown.md +++ b/docs/guide/markdown.md @@ -473,9 +473,13 @@ This is default theme built-in `` component ::: tip Check out the [Built-in Components](../reference/components.md) for a full list of built-in components. -Check out the [Default Theme > Built-in Components](../reference/default-theme/components.md) for a full list of default theme built-in components. +Check out the [Default Theme > Built-in Components](https://ecosystem.vuejs.press/themes/default/components.html) for a full list of default theme built-in components. ::: +## Markdown Plugins + +You can explore more markdown plugins at [VuePress Marketplace](https://marketplace.vuejs.press). + ## Cautions ### Non-Standard HTML Tags diff --git a/docs/guide/migration.md b/docs/guide/migration.md index e4350302..88e48e83 100644 --- a/docs/guide/migration.md +++ b/docs/guide/migration.md @@ -264,11 +264,11 @@ See [Frontmatter > permalinkPattern](../reference/frontmatter.md#permalinkpatter The stylus palette system of VuePress v1 (i.e. `styles/palette.styl` and `styles/index.styl`) is no longer provided by VuePress Core. -The palette system is extracted to [@vuepress/plugin-palette](../reference/plugin/palette.md). +The palette system is extracted to [@vuepress/plugin-palette](https://ecosystem.vuejs.press/plugins/palette.html). Theme authors can use their own way to allow users to customize styles, and not be limited with stylus. -If you are using default theme, the palette system is still available but migrated to SASS, while most variables have been migrated to CSS variables. See [Default Theme > Styles](../reference/default-theme/styles.md). +If you are using default theme, the palette system is still available but migrated to SASS, while most variables have been migrated to CSS variables. See [Default Theme > Styles](https://ecosystem.vuejs.press/themes/default/styles.html). ### Conventional Files Change @@ -282,7 +282,7 @@ See [Advanced > Cookbook > Usage of Client Config](../advanced/cookbook/usage-of Files in this directory will not be registered as Vue components automatically. -You need to use [@vuepress/plugin-register-components](../reference/plugin/register-components.md), or register your components manually in `.vuepress/client.{js,ts}`. +You need to use [@vuepress/plugin-register-components](https://ecosystem.vuejs.press/plugins/register-components.html), or register your components manually in `.vuepress/client.{js,ts}`. #### .vuepress/theme/ @@ -327,13 +327,13 @@ Removed. The palette system of default theme has migrated to SASS and CSS variables. -See [Default Theme > Styles](../reference/default-theme/styles.md). +See [Default Theme > Styles](https://ecosystem.vuejs.press/themes/default/styles.html). #### Theme Config Default theme config has been changed a lot. You'd better check the config reference of v2 default theme to migrate it properly. -See [Default Theme > Config](../reference/default-theme/config.md). +See [Default Theme > Config](https://ecosystem.vuejs.press/themes/default/config.html). Here we list some notable changes: @@ -412,13 +412,13 @@ Some major breaking changes: - There is no **conventional theme directory structure** anymore. - The file `theme/enhanceApp.js` will not be used as client app enhance file implicitly. You need to specify it explicitly in `clientConfigFile` hook. - - Files in `theme/global-components/` directory will not be registered as Vue components automatically. You need to use [@vuepress/plugin-register-components](../reference/plugin/register-components.md), or register components manually in `clientConfigFile`. + - Files in `theme/global-components/` directory will not be registered as Vue components automatically. You need to use [@vuepress/plugin-register-components](https://ecosystem.vuejs.press/plugins/register-components.html), or register components manually in `clientConfigFile`. - Files in `theme/layouts/` directory will not be registered as layout components automatically. You need to specify it explicitly in `layouts` option in `clientConfigFile`. - Files in `theme/templates/` directory will not be used as dev / ssr template automatically. You need to specify theme explicitly in `templateBuild` and `templateDev` option. - Always provide a valid js entry file, and do not use `"main": "layouts/Layout.vue"` as the theme entry anymore. -- `themeConfig` is removed from user config and site data. To access the `themeConfig` as you would via `this.$site.themeConfig` in v1, we now recommend using the [@vuepress/plugin-theme-data](../reference/plugin/theme-data.md) plugin and its `useThemeData` composition API. -- Stylus is no longer the default CSS pre-processor, and the stylus palette system is not embedded. If you still want to use similar palette system as v1, [@vuepress/plugin-palette](../reference/plugin/palette.md) may help. -- Markdown code blocks syntax highlighting by Prism.js is not embedded by default. You can use either [@vuepress/plugin-prismjs](../reference/plugin/prismjs.md) or [@vuepress/plugin-shiki](../reference/plugin/shiki.md), or implement syntax highlighting in your own way. +- `themeConfig` is removed from user config and site data. To access the `themeConfig` as you would via `this.$site.themeConfig` in v1, we now recommend using the [@vuepress/plugin-theme-data](https://ecosystem.vuejs.press/plugins/theme-data.html) plugin and its `useThemeData` composition API. +- Stylus is no longer the default CSS pre-processor, and the stylus palette system is not embedded. If you still want to use similar palette system as v1, [@vuepress/plugin-palette](https://ecosystem.vuejs.press/plugins/palette.html) may help. +- Markdown code blocks syntax highlighting by Prism.js is not embedded by default. You can use either [@vuepress/plugin-prismjs](https://ecosystem.vuejs.press/plugins/prismjs.html) or [@vuepress/plugin-shiki](https://ecosystem.vuejs.press/plugins/shiki.html), or implement syntax highlighting in your own way. - For scalability concerns, `this.$site.pages` is not available any more. For more detailed guide about how to write a theme in v2, see [Advanced > Writing a Theme](../advanced/theme.md). @@ -439,6 +439,6 @@ Renamed to `extends`. You can still inherit a parent theme with `extends: parentTheme()`, which will extends the plugins, layouts, etc. -You can refer to [Default Theme > Extending](../reference/default-theme/extending.md) for how to extend default theme. +You can refer to [Default Theme > Extending](https://ecosystem.vuejs.press/themes/default/extending.html) for how to extend default theme. The `@theme` and `@parent-theme` aliases are removed by default, but you can still make a extendable theme with similar approach, see [Advanced > Cookbook > Making a Theme Extendable](../advanced/cookbook/making-a-theme-extendable.md). diff --git a/docs/guide/page.md b/docs/guide/page.md index d8164fbb..1efe095f 100644 --- a/docs/guide/page.md +++ b/docs/guide/page.md @@ -58,7 +58,7 @@ Also, VuePress has built-in support for some frontmatter fields, and your theme ::: tip Check out the [Frontmatter Reference](../reference/frontmatter.md) for a full list of VuePress built-in frontmatter. -Check out the [Default Theme > Frontmatter Reference](../reference/default-theme/frontmatter.md) for the frontmatter of default theme. +Check out the [Default Theme > Frontmatter Reference](https://ecosystem.vuejs.press/themes/default/frontmatter.html) for the frontmatter of default theme. ::: ## Content diff --git a/docs/guide/plugin.md b/docs/guide/plugin.md index b5c4c37f..d9dd0b03 100644 --- a/docs/guide/plugin.md +++ b/docs/guide/plugin.md @@ -10,7 +10,7 @@ With the help of [Plugin API](../reference/plugin-api.md), VuePress plugin can p VuePress team provides some official plugins. -You need to import and use them in your config file via the [plugins](../reference/config.md#plugins) option. For example, use the [@vuepress/plugin-google-analytics](../reference/plugin/google-analytics.md) to integrate Google Analytics: +You need to import and use them in your config file via the [plugins](../reference/config.md#plugins) option. For example, use the [@vuepress/plugin-google-analytics](https://ecosystem.vuejs.press/plugins/google-analytics.html) to integrate Google Analytics: ```ts import { googleAnalyticsPlugin } from '@vuepress/plugin-google-analytics' @@ -27,14 +27,14 @@ export default { ::: tip Most plugins can only be used once. If the same plugin is used multiple times, only the last one will take effect. -However, some plugins can be used multiple times (e.g. [@vuepress/plugin-container](../reference/plugin/container.md)), and you should check the documentation of the plugin itself for detailed guide. +However, some plugins can be used multiple times (e.g. [@vuepress/plugin-container](https://ecosystem.vuejs.press/plugins/container.html)), and you should check the documentation of the plugin itself for detailed guide. ::: ## Community Plugin Community users have created lots of plugins and published them to [NPM](https://www.npmjs.com/search?q=keywords:vuepress-plugin). You should check the plugin's own documentation for detailed guide. -You can explore more plugins in [Awesome VuePress](https://github.com/vuepress/awesome-vuepress) or [VuePress Marketplace](https://marketplace.vuejs.press/). +You can explore more plugins in [VuePress Marketplace](https://marketplace.vuejs.press/). ## Local Plugin diff --git a/docs/guide/theme.md b/docs/guide/theme.md index 68921c5f..97a6860a 100644 --- a/docs/guide/theme.md +++ b/docs/guide/theme.md @@ -29,7 +29,7 @@ export default defineUserConfig({ }) ``` -The default theme provides basic but useful features for documentation site, you can check out [Default Theme Config Reference](../reference/default-theme/config.md) for a full list of config. +The default theme provides basic but useful features for documentation site, you can check out [Default Theme Config Reference](https://ecosystem.vuejs.press/themes/default/config.html) for a full list of config. However, you might think it is not good enough. Or, you want to build a different type of site, for example, a blog, instead of a documentation. Then, you can try to use a community theme or create a local theme. @@ -37,7 +37,7 @@ However, you might think it is not good enough. Or, you want to build a differen Community users have created lots of theme and published them to [NPM](https://www.npmjs.com/search?q=keywords:vuepress-theme). You should check the theme's own documentation for detailed guide. -You can explore more themes in [Awesome VuePress](https://github.com/vuepress/awesome-vuepress) or [VuePress Marketplace](https://marketplace.vuejs.press/). +You can explore more themes in [VuePress Marketplace](https://marketplace.vuejs.press/). ## Local Theme diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md new file mode 100644 index 00000000..1afa8d34 --- /dev/null +++ b/docs/guide/troubleshooting.md @@ -0,0 +1,14 @@ +# Troubleshooting + +## The bundler / theme option is missing? + +You need to set the bundler and theme to use explicitly in your config file. + +See the bundler reference for how to configure bundlers properly: + +- [Bundlers > Vite](../reference/bundler/vite.md) +- [Bundlers > Webpack](../reference/bundler/webpack.md) + +See the default theme reference for how to configure the default theme properly: + +- [Default Theme > Config](https://ecosystem.vuejs.press/themes/default/config.html) diff --git a/docs/reference/bundler/vite.md b/docs/reference/bundler/vite.md index 8ecb392d..f8a1a0ec 100644 --- a/docs/reference/bundler/vite.md +++ b/docs/reference/bundler/vite.md @@ -6,17 +6,19 @@ icon: simple-icons:vite -Vite bundler is provided by [@vuepress/bundler-vite](https://www.npmjs.com/package/@vuepress/bundler-vite) package. It is a dependency of the [vuepress](https://www.npmjs.com/package/vuepress) package, and you can also install it separately. +Vite bundler is provided by [@vuepress/bundler-vite](https://www.npmjs.com/package/@vuepress/bundler-vite) package. + +## Usage + +Install the bundler package: ```bash npm i -D @vuepress/bundler-vite@next ``` -## Options - -Reference of vite bundler options: +Specify the bundler option in your config file: -```ts +```ts title=".vuepress/config.ts" import { viteBundler } from '@vuepress/bundler-vite' import { defineUserConfig } from 'vuepress' @@ -28,6 +30,8 @@ export default defineUserConfig({ }) ``` +## Options + ### viteOptions - Details: diff --git a/docs/reference/bundler/webpack.md b/docs/reference/bundler/webpack.md index 1fe82f25..6eb58e22 100644 --- a/docs/reference/bundler/webpack.md +++ b/docs/reference/bundler/webpack.md @@ -6,17 +6,19 @@ icon: mdi:webpack -Webpack bundler is provided by [@vuepress/bundler-webpack](https://www.npmjs.com/package/@vuepress/bundler-webpack) package. It is a dependency of the [vuepress-webpack](https://www.npmjs.com/package/vuepress-webpack) package, and you can also install it separately. +Webpack bundler is provided by [@vuepress/bundler-webpack](https://www.npmjs.com/package/@vuepress/bundler-webpack) package. + +## Usage + +Install the bundler package: ```bash npm i -D @vuepress/bundler-webpack@next ``` -## Options - -Reference of webpack bundler options: +Specify the bundler option in your config file: -```ts +```ts title=".vuepress/config.ts" import { webpackBundler } from '@vuepress/bundler-webpack' import { defineUserConfig } from 'vuepress' @@ -28,6 +30,8 @@ export default defineUserConfig({ }) ``` +## Options + ### configureWebpack - Type: `(config: WebpackConfiguration, isServer: boolean, isBuild: boolean) => WebpackConfiguration | void` diff --git a/docs/reference/cli.md b/docs/reference/cli.md index fd023015..fbd98073 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -10,7 +10,7 @@ VuePress CLI is provided by [@vuepress/cli](https://www.npmjs.com/package/@vuepr Run `vuepress --help` to get following help messages: -```bash +``` Usage: $ vuepress [options] @@ -39,7 +39,7 @@ Set environment variable `DEBUG=vuepress*` to enable debug logs. Start a development server to develop your VuePress site locally. -```bash +``` Usage: $ vuepress dev [sourceDir] @@ -66,7 +66,7 @@ Options set by CLI will override those options with the same name in your config Build your VuePress site to static files, which are ready for [deployment](../guide/deployment.md). -```bash +``` Usage: $ vuepress build [sourceDir] diff --git a/docs/reference/default-theme/components.md b/docs/reference/default-theme/components.md deleted file mode 100644 index 40f16e18..00000000 --- a/docs/reference/default-theme/components.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -icon: fa6-solid:puzzle-piece ---- - -# Built-in Components - - - -## Badge - -- Props: - - - type - - Type: `'tip' | 'warning' | 'danger'` - - Default: `'tip'` - - text - - Type: `string` - - Default: `''` - - vertical - - Type: `'top' | 'middle' | 'bottom' | undefined` - - Default: `undefined` - -- Example: - -**Input** - -```md -- VuePress - -- VuePress - -- VuePress - -``` - -**Output** - -- VuePress - -- VuePress - -- VuePress - - -## CodeGroup - -- Details: - - Wrapper of the [CodeGroupItem](#codegroupitem) components. - -## CodeGroupItem - -- Props: - - - title - - Type: `string` - - Required: `true` - - active - - Type: `boolean` - - Default: `false` - -- Details: - - This component must be placed inside a [CodeGroup](#codegroup) component. - - Use the `active` prop to set the initial active item, or the first item will be activated by default. - -- Example: - -**Input** - -````md - - - -```bash:no-line-numbers -pnpm install -``` - - - - - -```bash:no-line-numbers -yarn install -``` - - - - - -```bash:no-line-numbers -npm install -``` - - - -```` - -**Output** - -::: code-tabs - -@tab pnpm - -```bash:no-line-numbers -pnpm install -``` - -@tab yarn - -```bash:no-line-numbers -yarn install -``` - -@tab:active npm - -```bash:no-line-numbers -npm install -``` - -::: - -::: warning -You must add an empty line between the starting tag of `` and the code fence, otherwise the code fence will not be parsed correctly by Markdown. - -All content must be valid Markdown first, and then a Vue SFC. - -Learn more: [Cookbook > Markdown and Vue SFC](../../advanced/cookbook/markdown-and-vue-sfc.md) - -Alternatively, you can use the [custom containers](./markdown.md#custom-containers). -::: diff --git a/docs/reference/default-theme/config.md b/docs/reference/default-theme/config.md deleted file mode 100644 index 04739a44..00000000 --- a/docs/reference/default-theme/config.md +++ /dev/null @@ -1,750 +0,0 @@ ---- -icon: fa6-solid:gear ---- - -# Config - - - -```ts -import { defaultTheme } from '@vuepress/theme-default' - -export default { - theme: defaultTheme({ - // set config here - }), -} -``` - -## Basic Config - -### locales - -- Type: `{ [path: string]: Partial }` - -- Default: `{}` - -- Details: - - Specify locales for i18n support. - - All the options inside the [Locale Config](#locale-config) section can be used in locales. - - This option will only take effect in default theme, so don't confuse with `locales` in [Site Config](../config.md#locales). - -- Also see: - - [Guide > I18n](../../guide/i18n.md) - -## Locale Config - -Config of this section can be used as normal config, and can also be used in the [locales](#locales) option. - -### colorMode - -- Type: `'auto' | 'light' | 'dark'` - -- Default: `'auto'` - -- Details: - - Default color mode. - - If set to `'auto'`, the initial color mode will be automatically set according to [prefers-color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme). - -- Also see: - - [Default Theme > Config > colorModeSwitch](#colormodeswitch) - -### colorModeSwitch - -- Type: `boolean` - -- Default: `true` - -- Details: - - Enable color mode switching or not. - - If set to `true`, a button to switch color mode will be displayed in the navbar. - -- Also see: - - [Default Theme > Config > colorMode](#colormode) - - [Default Theme > Config > toggleColorMode](#togglecolormode) - -### home - -- Type: `string` - -- Default: `/` - -- Details: - - Specify the path of the homepage. - - This will be used for: - - - the logo link of the navbar - - the _back to home_ link of the 404 page - -### navbar - -- Type: `false | (NavbarItem | NavbarGroup | string)[]` - -- Default: `[]` - -- Details: - - Configuration of navbar. - - Set to `false` to disable navbar. - - To configure the navbar items, you can set it to a _navbar array_, each item of which could be a `NavbarItem` object, a `NavbarGroup` object, or a string: - - - A `NavbarItem` object should have a `text` field and a `link` field, could have an optional `activeMatch` field. - - A `NavbarGroup` object should have a `text` field and a `children` field. The `children` field should be a _navbar array_, too. - - A string should be the path to the target page file. It will be converted to a `NavbarItem` object, using the page title as `text`, and the page route path as `link`. - -- Example 1: - -```ts -export default { - theme: defaultTheme({ - navbar: [ - // NavbarItem - { - text: 'Foo', - link: '/foo/', - }, - // NavbarGroup - { - text: 'Group', - children: ['/group/foo.md', '/group/bar.md'], - }, - // string - page file path - '/bar/README.md', - ], - }), -} -``` - -- Example 2: - -```ts -export default { - theme: defaultTheme({ - navbar: [ - // nested group - max depth is 2 - { - text: 'Group', - children: [ - { - text: 'SubGroup', - children: ['/group/sub/foo.md', '/group/sub/bar.md'], - }, - ], - }, - // control when should the item be active - { - text: 'Group 2', - children: [ - { - text: 'Always active', - link: '/', - // this item will always be active - activeMatch: '/', - }, - { - text: 'Active on /foo/', - link: '/not-foo/', - // this item will be active when current route path starts with /foo/ - // regular expression is supported - activeMatch: '^/foo/', - }, - ], - }, - ], - }), -} -``` - -### logo - -- Type: `null | string` - -- Details: - - Specify the url of logo image. - - The logo image will be displayed at the left end of the navbar. - - Set to `null` to disable logo. - -- Example: - -```ts -export default { - theme: defaultTheme({ - // public file path - logo: '/hero.png', - // url - logo: 'https://vuejs.org/images/logo.png', - }), -} -``` - -- Also see: - - [Guide > Assets > Public Files](../../guide/assets.md#public-files) - -### logoDark - -- Type: `null | string` - -- Details: - - Specify the url of logo image to be used in dark mode. - - You can make use of this option if you want to use different logo config in dark mode. - - Set to `null` to disable logo in dark mode. Omit this option to use [logo](#logo) in dark mode. - -- Also see: - - [Default Theme > Config > logo](#logo) - - [Default Theme > Config > colorMode](#colormode) - -### repo - -- Type: `string` - -- Details: - - Specify the repository url of your project. - - This will be used as the link of the _repository link_, which will be displayed as the last item of the navbar. - -```ts -export default { - theme: defaultTheme({ - // If you set it in the form of `organization/repository` - // we will take it as a GitHub repo - repo: 'vuejs/vuepress', - // You can also set it to a URL directly - repo: 'https://gitlab.com/foo/bar', - }), -} -``` - -### repoLabel - -- Type: `string` - -- Details: - - Specify the repository label of your project. - - This will be used as the text of the _repository link_, which will be displayed as the last item of the navbar. - - If you don't set this option explicitly, it will be automatically inferred from the [repo](#repo) option. - -### selectLanguageText - -- Type: `string` - -- Details: - - Specify the text of the _select language menu_. - - The _select language menu_ will appear next to the repository button in the navbar when you set multiple [locales](../config.md#locales) in your site config. - -### selectLanguageAriaLabel - -- Type: `string` - -- Details: - - Specify the `aria-label` attribute of the _select language menu_. - - This is mainly for a11y purpose. - -### selectLanguageName - -- Type: `string` - -- Details: - - Specify the name of the language of a locale. - - This option will **only take effect inside** the [locales](#locales) of your theme config. It will be used as the language name of the locale, which will be displayed in the _select language menu_. - -- Example: - -```ts -export default { - locales: { - '/': { - lang: 'en-US', - }, - '/zh/': { - lang: 'zh-CN', - }, - }, - theme: defaultTheme({ - locales: { - '/': { - selectLanguageName: 'English', - }, - '/zh/': { - selectLanguageName: '简体中文', - }, - }, - }), -} -``` - -### sidebar - -- Type: `false | 'auto' | SidebarConfigArray | SidebarConfigObject` - -- Default: `'auto'` - -- Details: - - Configuration of sidebar. - - You can override this global option via [sidebar](./frontmatter.md#sidebar) frontmatter in your pages. - - Set to `false` to disable sidebar. - - If you set it to `'auto'`, the sidebar will be automatically generated from the page headers. - - To configure the sidebar items manually, you can set this option to a _sidebar array_, each item of which could be a `SidebarItem` object or a string: - - - A `SidebarItem` object should have a `text` field, could have an optional `link` field, an optional `children` field and an optional `collapsible` field. The `children` field should be a _sidebar array_. The `collapsible` field controls whether the item is collapsible. - - A string should be the path to the target page file. It will be converted to a `SidebarItem` object, whose `text` is the page title, `link` is the page route path, and `children` is automatically generated from the page headers. - - If you want to set different sidebar for different sub paths, you can set this option to a _sidebar object_: - - - The key should be the path prefix. - - The value should be a _sidebar array_. - -- Example 1: - -```ts -export default { - theme: defaultTheme({ - // sidebar array - // all pages will use the same sidebar - sidebar: [ - // SidebarItem - { - text: 'Foo', - link: '/foo/', - children: [ - // SidebarItem - { - text: 'github', - link: 'https://github.com', - children: [], - }, - // string - page file path - '/foo/bar.md', - ], - }, - // string - page file path - '/bar/README.md', - ], - }), -} -``` - -- Example 2: - -```ts -export default { - theme: defaultTheme({ - // sidebar object - // pages under different sub paths will use different sidebar - sidebar: { - '/guide/': [ - { - text: 'Guide', - children: ['/guide/introduction.md', '/guide/getting-started.md'], - }, - ], - '/reference/': [ - { - text: 'Reference', - children: ['/reference/cli.md', '/reference/config.md'], - }, - ], - }, - }), -} -``` - -- Example 3: - -```ts -export default { - theme: defaultTheme({ - // collapsible sidebar - sidebar: { - '/reference/': [ - { - text: 'VuePress Reference', - collapsible: true, - children: ['/reference/cli.md', '/reference/config.md'], - }, - { - text: 'Bundlers Reference', - collapsible: true, - children: [ - '/reference/bundler/vite.md', - '/reference/bundler/webpack.md', - ], - }, - ], - }, - }), -} -``` - -### sidebarDepth - -- Type: `number` - -- Default: `2` - -- Details: - - Set the maximum depth of the sidebar children which are automatically generated from the page headers. - - - Set to `0` to disable all levels of headers. - - Set to `1` to include `

` headers. - - Set to `2` to include `

` and `

` headers. - - ... - - The max value depends on which levels of headers you have extracted via [markdown.headers.level](../config.md#markdown-headers). - - The default value of `markdown.headers.level` is `[2, 3]`, so the default max value of `sidebarDepth` is `2`. - - You can override this global option via [sidebarDepth](./frontmatter.md#sidebardepth) frontmatter in your pages. - -### editLink - -- Type: `boolean` - -- Default: `true` - -- Details: - - Enable the _edit this page_ link or not. - - You can override this global option via [editLink](./frontmatter.md#editlink) frontmatter in your pages. - -### editLinkText - -- Type: `string` - -- Default: `'Edit this page'` - -- Details: - - Specify the text of the _edit this page_ link. - -### editLinkPattern - -- Type: `string` - -- Details: - - Specify the pattern of the _edit this page_ link. - - This will be used for generating the _edit this page_ link. - - If you don't set this option, the pattern will be inferred from the [docsRepo](#docsrepo) option. But if your documentation repository is not hosted on a common platform, for example, GitHub, GitLab, Bitbucket, Gitee, etc., you have to set this option explicitly to make the _edit this page_ link work. - -- Usage: - - | Pattern | Description | - | --------- | --------------------------------------------------------------------------------------------------- | - | `:repo` | The docs repo url, i.e. [docsRepo](#docsrepo) | - | `:branch` | The docs repo branch, i.e. [docsBranch](#docsbranch) | - | `:path` | The path of the page source file, i.e. [docsDir](#docsdir) joins the relative path of the page file | - -- Example: - -```ts -export default { - theme: defaultTheme({ - docsRepo: 'https://gitlab.com/owner/name', - docsBranch: 'master', - docsDir: 'docs', - editLinkPattern: ':repo/-/edit/:branch/:path', - }), -} -``` - -The generated link will look like `'https://gitlab.com/owner/name/-/edit/master/docs/path/to/file.md'`. - -### docsRepo - -- Type: `string` - -- Details: - - Specify the repository url of your documentation source files. - - This will be used for generating the _edit this page_ link. - - If you don't set this option, it will use the [repo](#repo) option by default. But if your documentation source files are in a different repository, you will need to set this option. - -### docsBranch - -- Type: `string` - -- Default: `'main'` - -- Details: - - Specify the repository branch of your documentation source files. - - This will be used for generating the _edit this page_ link. - -### docsDir - -- Type: `string` - -- Default: `''` - -- Details: - - Specify the directory of your documentation source files in the repository. - - This will be used for generating the _edit this page_ link. - -### lastUpdated - -- Type: `boolean` - -- Default: `true` - -- Details: - - Enable the _last updated timestamp_ or not. - - You can override this global option via [lastUpdated](./frontmatter.md#lastupdated) frontmatter in your pages. Notice that if you have already set this option to `false`, this feature will be disabled totally and could not be enabled in locales nor page frontmatter. - -### lastUpdatedText - -- Type: `string` - -- Default: `'Last Updated'` - -- Details: - - Specify the text of the _last updated timestamp_ label. - -### contributors - -- Type: `boolean` - -- Default: `true` - -- Details: - - Enable the _contributors list_ or not. - - You can override this global option via [contributors](./frontmatter.md#contributors) frontmatter in your pages. Notice that if you have already set this option to `false`, this feature will be disabled totally and could not be enabled in locales nor page frontmatter. - -### contributorsText - -- Type: `string` - -- Default: `'Contributors'` - -- Details: - - Specify the text of the _contributors list_ label. - -### tip - -- Type: `string` - -- Default: `'TIP'` - -- Details: - - Specify the default title of the tip [custom containers](./markdown.md#custom-containers). - -### warning - -- Type: `string` - -- Default: `'WARNING'` - -- Details: - - Specify the default title of the warning [custom containers](./markdown.md#custom-containers). - -### danger - -- Type: `string` - -- Default: `'DANGER'` - -- Details: - - Specify the default title of the danger [custom containers](./markdown.md#custom-containers). - -### notFound - -- Type: `string[]` - -- Default: `['Not Found']` - -- Details: - - Specify the messages of the 404 page. - - The message will be randomly picked from the array when users enter the 404 page. - -### backToHome - -- Type: `string` - -- Default: `'Back to home'` - -- Details: - - Specify the text of the _back to home_ link in the 404 page. - -### openInNewWindow - -- Type: `string` - -- Default: `'open in new window'` - -- Details: - - Specify the `sr-only` text of the [ExternalLinkIcon](../plugin/external-link-icon.md#externallinkicon). - - This is mainly for a11y purpose. - -- Also see: - - [Default Theme > Config Reference > themePlugins.externalLinkIcon](#themeplugins-externallinkicon) - -### toggleColorMode - -- Type: `string` - -- Default: `'toggle color mode'` - -- Details: - - Title text for the color mode toggle button. - - This is mainly for a11y purpose. - -- Also see: - - [Default Theme > Config > colorModeSwitch](#colormodeswitch) - -### toggleSidebar - -- Type: `string` - -- Default: `'toggle sidebar'` - -- Details: - - Title text for sidebar toggle button. - - This is mainly for a11y purpose. - -## Plugins Config - -### themePlugins - -- Details: - - Configure the plugins that used by default theme. - - Default theme is using some plugins by default. You can disable a plugin if you really do not want to use it. Make sure you understand what the plugin is for before disabling it. - -### themePlugins.activeHeaderLinks - -- Type: `boolean` - -- Default: `true` - -- Details: - - Enable [@vuepress/plugin-active-header-links](../plugin/active-header-links.md) or not. - -### themePlugins.backToTop - -- Type: `boolean` - -- Default: `true` - -- Details: - - Enable [@vuepress/plugin-back-to-top](../plugin/back-to-top.md) or not. - -### themePlugins.container - -- Type: `Record` - -- Details: - - Enable custom containers that powered by [@vuepress/plugin-container](../plugin/container.md) or not. - - `ContainerType` type is: - - - `tip` - - `warning` - - `danger` - - `details` - - `codeGroup` - - `codeGroupItem` - -- Also see: - - [Default Theme > Markdown > Custom Containers](./markdown.md#custom-containers) - -### themePlugins.externalLinkIcon - -- Type: `boolean` - -- Default: `true` - -- Details: - - Enable [@vuepress/plugin-external-link-icon](../plugin/external-link-icon.md) or not. - -### themePlugins.git - -- Type: `boolean` - -- Default: `true` - -- Details: - - Enable [@vuepress/plugin-git](../plugin/git.md) or not. - -### themePlugins.mediumZoom - -- Type: `boolean` - -- Default: `true` - -- Details: - - Enable [@vuepress/plugin-medium-zoom](../plugin/medium-zoom.md) or not. - -### themePlugins.nprogress - -- Type: `boolean` - -- Default: `true` - -- Details: - - Enable [@vuepress/plugin-nprogress](../plugin/nprogress.md) or not. diff --git a/docs/reference/default-theme/extending.md b/docs/reference/default-theme/extending.md deleted file mode 100644 index dca7f791..00000000 --- a/docs/reference/default-theme/extending.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -icon: fa6-solid:clone ---- - -# Extending - -VuePress default theme is widely used by users, so it is designed to be extendable, allowing users to make their own customization with ease. - -VuePress provides basic ability to extend a theme, but different themes may have different features to be extended. Thus, if you are using a community theme, you'd better refer to the theme's own documentation for how to extending it. - -## Layout Slots - -Default theme's `Layout` provides some slots: - -- `navbar` -- `navbar-before` -- `navbar-after` -- `sidebar` -- `sidebar-top` -- `sidebar-bottom` -- `page` -- `page-top` -- `page-bottom` -- `page-content-top` -- `page-content-bottom` - -With the help of them, you can add or replace content easily. Here comes an example to introduce how to extend default theme with layout slots. - -Firstly, create a client config file `.vuepress/client.ts`: - -```ts -import { defineClientConfig } from 'vuepress/client' -import Layout from './layouts/Layout.vue' - -export default defineClientConfig({ - layouts: { - Layout, - }, -}) -``` - -Next, create the `.vuepress/layouts/Layout.vue`, and make use of the slots that provided by the `Layout` of default theme: - -```vue - - - - - -``` - -Then the default `Layout` layout has been overridden by your own local layout, which will add a custom footer to every normal pages in default theme (excluding homepage): - -![extending-a-theme](/images/cookbook/extending-a-theme-01.png) - -## Components Replacement - -The layout slots are useful, but sometimes you might find it's not flexible enough. Default theme also provides the ability to replace a single component. - -Default theme has registered [alias](../plugin-api.md#alias) for every [non-global components](https://github.com/vuepress/ecosystem/tree/main/themes/theme-default/src/client/components) with a `@theme` prefix. For example, the alias of `HomeFooter.vue` is `@theme/HomeFooter.vue`. - -Then, if you want to replace the `HomeFooter.vue` component, just override the alias in your config file `.vuepress/config.ts`: - -```ts -import { defaultTheme } from '@vuepress/theme-default' -import { getDirname, path } from 'vuepress/utils' -import { defineUserConfig } from 'vuepress' - -const __dirname = getDirname(import.meta.url) - -export default defineUserConfig({ - theme: defaultTheme(), - alias: { - '@theme/HomeFooter.vue': path.resolve( - __dirname, - './components/MyHomeFooter.vue', - ), - }, -}) -``` - -## Developing a Child Theme - -Instead of extending the default theme directly in `.vuepress/config.ts` and `.vuepress/client.ts`, you can also develop your own theme extending the default theme: - -```ts -import { defaultTheme, type DefaultThemeOptions } from '@vuepress/theme-default' -import type { Theme } from 'vuepress/core' -import { getDirname, path } from 'vuepress/utils' - -const __dirname = getDirname(import.meta.url) - -export const childTheme = (options: DefaultThemeOptions): Theme => { - return { - name: 'vuepress-theme-child', - extends: defaultTheme(options), - - // override layouts in child theme's client config file - // notice that you would build ts to js before publishing to npm, - // so this should be the path to the js file - clientConfigFile: path.resolve(__dirname, './client.js'), - - // override component alias - alias: { - '@theme/HomeFooter.vue': path.resolve( - __dirname, - './components/MyHomeFooter.vue', - ), - }, - } -} -``` diff --git a/docs/reference/default-theme/frontmatter.md b/docs/reference/default-theme/frontmatter.md deleted file mode 100644 index 5a93bb81..00000000 --- a/docs/reference/default-theme/frontmatter.md +++ /dev/null @@ -1,364 +0,0 @@ ---- -icon: fa-solid:bars ---- - -# Frontmatter - - - -## All Pages - -Frontmatter in this section will take effect in all types of pages. - -### externalLinkIcon - -- Type: `boolean` - -- Details: - - Provided by [@vuepress/plugin-external-link-icon](../plugin/external-link-icon.md#externallinkicon). - -- Also see: - - [Default Theme > Config Reference > themePlugins.externalLinkIcon](./config.md#themeplugins-externallinkicon) - -### navbar - -- Type: `boolean` - -- Details: - - Show navbar on this page or not. - - If you disable navbar in theme config, this frontmatter will not take effect. - -- Also see: - - [Default Theme > Config > navbar](./config.md#navbar) - -### pageClass - -- Type: `string` - -- Details: - - Add extra class name to this page. - -- Example: - -```md ---- -pageClass: custom-page-class ---- -``` - -Then you can customize styles of this page in `.vuepress/styles/index.scss` file: - -```scss -.theme-container.custom-page-class { - /* page styles */ -} -``` - -- Also see: - - [Default Theme > Styles > Style File](./styles.md#style-file) - -## Home Page - -Frontmatter in this section will only take effect in home pages. - -### home - -- Type: `boolean` - -- Details: - - Specify whether the page is homepage or a normal page. - - If you don't set this frontmatter or set it to `false`, the page would be a [normal page](#normal-page). - -- Example: - -```md ---- -home: true ---- -``` - -### heroImage - -- Type: `string` - -- Details: - - Specify the url of the hero image. - -- Example: - -```md ---- -# public file path -heroImage: /images/hero.png -# url -heroImage: https://vuejs.org/images/logo.png ---- -``` - -- Also see: - - [Guide > Assets > Public Files](../../guide/assets.md#public-files) - -### heroImageDark - -- Type: `string` - -- Details: - - Specify the url of hero image to be used in dark mode. - - You can make use of this option if you want to use different heroImage config in dark mode. - -- Also see: - - [Default Theme > Frontmatter > heroImage](#heroimage) - - [Default Theme > Config > colorMode](./config.md#colormode) - -### heroAlt - -- Type: `string` - -- Details: - - Specify the `alt` attribute of the hero image. - - This will fallback to the [heroText](#herotext). - -### heroHeight - -- Type: `number` - -- Default: `280` - -- Details: - - Specify the `height` attribute of the hero `` tag. - - You may need to reduce this value if the height of your hero image is less than the default value. - - Notice that the height is also constrained by CSS. This attribute is to reduce [Cumulative Layout Shift (CLS)](https://web.dev/cls/) that caused by the loading of the hero image. - -### heroText - -- Type: `string | null` - -- Details: - - Specify the the hero text. - - This will fallback to the site [title](../config.md#title). - - Set to `null` to disable hero text. - -### tagline - -- Type: `string | null` - -- Details: - - Specify the the tagline. - - This will fallback to the site [description](../config.md#description). - - Set to `null` to disable tagline. - -### actions - -- Type: - -```ts -Array<{ - text: string - link: string - type?: 'primary' | 'secondary' -}> -``` - -- Details: - - Configuration of the action buttons. - -- Example: - -```md ---- -actions: - - text: Get Started - link: /guide/getting-started.html - type: primary - - text: Introduction - link: /guide/introduction.html - type: secondary ---- -``` - -### features - -- Type: - -```ts -Array<{ - title: string - details: string -}> -``` - -- Details: - - Configuration of the features list. - -- Example: - -```md ---- -features: - - title: Simplicity First - details: Minimal setup with markdown-centered project structure helps you focus on writing. - - title: Vue-Powered - details: Enjoy the dev experience of Vue, use Vue components in markdown, and develop custom themes with Vue. - - title: Performant - details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded. ---- -``` - -### footer - -- Type: `string` - -- Details: - - Specify the content of the footer. - -### footerHtml - -- Type: `boolean` - -- Details: - - Allow HTML in footer or not. - - If you set it to `true`, the [footer](#footer) will be treated as HTML code. - -## Normal Page - -Frontmatter in this section will only take effect in normal pages. - -### editLink - -- Type: `boolean` - -- Details: - - Enable the _edit this page_ link in this page or not. - -- Also see: - - [Default Theme > Config > editLink](./config.md#editlink) - -### editLinkPattern - -- Type: `string` - -- Details: - - Specify the pattern of the _edit this page_ link of this page. - -- Also see: - - [Default Theme > Config > editLinkPattern](./config.md#editlinkpattern) - -### lastUpdated - -- Type: `boolean` - -- Details: - - Enable the _last updated timestamp_ in this page or not. - -- Also see: - - [Default Theme > Config > lastUpdated](./config.md#lastupdated) - -### contributors - -- Type: `boolean` - -- Details: - - Enable the _contributors list_ in this page or not. - -- Also see: - - [Default Theme > Config > contributors](./config.md#contributors) - -### sidebar - -- Type: `false | 'auto' | SidebarConfigArray | SidebarConfigObject` - -- Details: - - Configure the sidebar of this page. - -- Also see: - - [Default Theme > Config > sidebar](./config.md#sidebar) - -### sidebarDepth - -- Type: `number` - -- Details: - - Configure the sidebar depth of this page. - -- Also see: - - [Default Theme > Config > sidebarDepth](./config.md#sidebardepth) - -### prev - -- Type: `NavLink | string` - -- Details: - - Specify the link of the previous page. - - If you don't set this frontmatter, the link will be inferred from the sidebar config. - - To configure the prev link manually, you can set this frontmatter to a `NavLink` object or a string: - - - A `NavLink` object should have a `text` field and a `link` field. - - A string should be the path to the target page file. It will be converted to a `NavLink` object, whose `text` is the page title, and `link` is the page route path. - -- Example: - -```md ---- -# NavLink -prev: - text: Get Started - link: /guide/getting-started.html - -# NavLink - external url -prev: - text: GitHub - link: https://github.com - -# string - page file path -prev: /guide/getting-started.md - -# string - page file relative path -prev: ../../guide/getting-started.md ---- -``` - -### next - -- Type: `NavLink | string` - -- Details: - - Specify the link of the next page. - - If you don't set this frontmatter, the link will be inferred from the sidebar config. - - The type is the same as [prev](#prev) frontmatter. diff --git a/docs/reference/default-theme/markdown.md b/docs/reference/default-theme/markdown.md deleted file mode 100644 index 319730bf..00000000 --- a/docs/reference/default-theme/markdown.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -icon: fa6-brands:markdown ---- - -# Markdown - - - -## Custom Containers - -- Usage: - - ```md - ::: [title] - [content] - ::: - ``` - - The `type` is required, and the `title` and `content` are optional. - - Supported `type` : - - - `tip` - - `warning` - - `danger` - - `details` - - Alias of [CodeGroup](./components.md#codegroup) and [CodeGroupItem](./components.md#codegroupitem): - - `code-group` - - `code-group-item` - -- Example 1 (default title): - -**Input** - -```md -::: tip -This is a tip -::: - -::: warning -This is a warning -::: - -::: danger -This is a dangerous warning -::: - -::: details -This is a details block -::: -``` - -**Output** - -::: tip -This is a tip -::: - -::: warning -This is a warning -::: - -::: danger -This is a dangerous warning -::: - -::: details -This is a details block -::: - -- Example 2 (custom title): - -**Input** - -````md -::: danger STOP -Danger zone, do not proceed -::: - -::: details Click me to view the code - -```ts -console.log('Hello, VuePress!') -``` - -::: -```` - -**Output** - -::: danger STOP -Danger zone, do not proceed -::: - -::: details Click me to view the code - -```ts -console.log('Hello, VuePress!') -``` - -::: - -- Example 3 (code group alias): - -**Input** - -````md -:::: code-group -::: code-group-item FOO - -```ts -const foo = 'foo' -``` - -::: - -::: code-group-item BAR - -```ts -const bar = 'bar' -``` - -::: -:::: -```` - -**Output** - -::: code-tabs - -@tab FOO - -```ts -const foo = 'foo' -``` - -@tab BAR - -```ts -const bar = 'bar' -``` - -::: diff --git a/docs/reference/default-theme/styles.md b/docs/reference/default-theme/styles.md deleted file mode 100644 index f6d2bbfc..00000000 --- a/docs/reference/default-theme/styles.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -icon: fa6-solid:wand-magic-sparkles ---- - -# Styles - - - -The default theme uses [SASS](https://sass-lang.com/) as the CSS pre-processor. - -Users can customize style variables via a [palette file](#palette-file), -and add extra styles via a [style file](#style-file). - -## Palette File - -The path of the palette file is `.vuepress/styles/palette.scss`. - -You can make use of it to override predefined SASS variables of the default theme. - -::: details Click to expand SASS variables -@[code{3-} scss](@vuepress/theme-default/src/client/styles/_variables.scss) -::: - -## Style File - -The path of the style file is `.vuepress/styles/index.scss`. - -You can add extra styles here, or override the default styles: - -```scss -:root { - scroll-behavior: smooth; -} -``` - -You can also make use of it to override predefined CSS variables of the default theme. - -::: details Click to expand CSS variables -@[code scss](@vuepress/theme-default/src/client/styles/vars.scss) -::: - -::: details Click to expand dark mode CSS variables -@[code scss](@vuepress/theme-default/src/client/styles/vars-dark.scss) -::: diff --git a/docs/reference/plugin/active-header-links.md b/docs/reference/plugin/active-header-links.md deleted file mode 100644 index a4b0ca0b..00000000 --- a/docs/reference/plugin/active-header-links.md +++ /dev/null @@ -1,74 +0,0 @@ -# active-header-links - - - -This plugin will listen to page scroll event. When the page scrolls to a certain _header anchor_, this plugin will change the route hash to that _header anchor_ if there is a corresponding _header link_. - -This plugin is mainly used to develop themes, and has been integrated into the default theme. You won't need to use it directly in most cases. - -## Usage - -```bash -npm i -D @vuepress/plugin-active-header-links@next -``` - -```ts -import { activeHeaderLinksPlugin } from '@vuepress/plugin-active-header-links' - -export default { - plugins: [ - activeHeaderLinksPlugin({ - // options - }), - ], -} -``` - -## Options - -### headerLinkSelector - -- Type: `string` - -- Default: `'a.sidebar-item'` - -- Details: - - Selector of _header link_. - - If a _header anchor_ does not have a corresponding _header link_, this plugin won't change the route hash to that anchor when scrolling to it. - -### headerAnchorSelector - -- Type: `string` - -- Default: `'.header-anchor'` - -- Details: - - Selector of _header anchor_. - - You don't need to specify this option unless you have changed the `permalinkClass` option of [markdown-it-anchor](https://github.com/valeriangalliat/markdown-it-anchor#readme) via [markdown.anchor](../config.md#markdown-anchor). - -- Also see: - - [Guide > Markdown > Syntax Extensions > Header Anchors](../../guide/markdown.md#header-anchors) - -### delay - -- Type: `number` - -- Default: `200` - -- Details: - - The delay of the debounced scroll event listener. - -### offset - -- Type: `number` - -- Default: `5` - -- Details: - - Even if you click the link of the _header anchor_ directly, the `scrollTop` might not be exactly equal to `offsetTop` of the _header anchor_, so we add an offset to avoid the error. diff --git a/docs/reference/plugin/back-to-top.md b/docs/reference/plugin/back-to-top.md deleted file mode 100644 index 6e959648..00000000 --- a/docs/reference/plugin/back-to-top.md +++ /dev/null @@ -1,27 +0,0 @@ -# back-to-top - - - -This plugin will add a _back to top_ button to your site. The button will be displayed in the bottom right corner of the page when scrolling down. By clicking the button, the page will scroll to the top. - -This plugin has been integrated into the default theme. - -## Usage - -```bash -npm i -D @vuepress/plugin-back-to-top@next -``` - -```ts -import { backToTopPlugin } from '@vuepress/plugin-back-to-top' - -export default { - plugins: [backToTopPlugin()], -} -``` - -## Styles - -You can customize the style of the _back to top_ button via CSS variables: - -@[code css](@vuepress/plugin-back-to-top/src/client/styles/vars.css) diff --git a/docs/reference/plugin/docsearch.md b/docs/reference/plugin/docsearch.md deleted file mode 100644 index 0b437553..00000000 --- a/docs/reference/plugin/docsearch.md +++ /dev/null @@ -1,411 +0,0 @@ -# docsearch - - - -Integrate [Algolia DocSearch](https://docsearch.algolia.com/) into VuePress, which can provide search to your documentation site. - -::: tip -Default theme will add DocSearch to the navbar once you configure this plugin correctly. - -This plugin may not be used directly in other themes, so you'd better refer to the documentation of your theme for more details. -::: - -## Usage - -```bash -npm i -D @vuepress/plugin-docsearch@next -``` - -```ts -import { docsearchPlugin } from '@vuepress/plugin-docsearch' - -export default { - plugins: [ - docsearchPlugin({ - // options - }), - ], -} -``` - -## Get Search Index - -You need to [submit the URL of your site](https://docsearch.algolia.com/apply/) to join the DocSearch program. The DocSearch team will send [apiKey](#apikey) and [indexName](#indexname) to your email once the index is generated. Then you can configure this plugin to enable DocSearch in VuePress. - -Alternatively, you can [run your own crawler](https://docsearch.algolia.com/docs/run-your-own/) to generate the index, and then use your own [appId](#appId), [apiKey](#apikey) and [indexName](#indexname) to configure this plugin. - -::: details Official crawler config - -```js{35-50,59} -new Crawler({ - appId: 'YOUR_APP_ID', - apiKey: 'YOUR_API_KEY', - rateLimit: 8, - startUrls: [ - // These are urls which algolia start to craw - // If your site is divided in to mutiple parts, - // you may want to set mutiple entry links - 'https://YOUR_WEBSITE_URL/', - ], - sitemaps: [ - // if you are using sitemap plugins (e.g.: vuepress-plugin-sitemap2), you may provide one - 'https://YOUR_WEBSITE_URL/sitemap.xml', - ], - ignoreCanonicalTo: false, - exclusionPatterns: [ - // You can use this to stop algolia crawing some paths - ], - discoveryPatterns: [ - // These are urls which algolia looking for, - 'https://YOUR_WEBSITE_URL/**', - ], - // Crawler schedule, set it according to your docs update frequency - schedule: 'at 02:00 every 1 day', - actions: [ - // you may have mutiple actions, especially when you are deploying mutiple docs under one domain - { - // name the index with name you like - indexName: 'YOUR_INDEX_NAME', - // paths where the index take effect - pathsToMatch: ['https://YOUR_WEBSITE_URL/**'], - // controls how algolia extracts records from your site - recordExtractor: ({ $, helpers }) => { - // options for @vuepress/theme-default - return helpers.docsearch({ - recordProps: { - lvl0: { - selectors: '.sidebar-heading.active', - defaultValue: 'Documentation', - }, - lvl1: '.theme-default-content h1', - lvl2: '.theme-default-content h2', - lvl3: '.theme-default-content h3', - lvl4: '.theme-default-content h4', - lvl5: '.theme-default-content h5', - lvl6: '.theme-default-content h6', - content: '.theme-default-content p, .theme-default-content li', - }, - indexHeadings: true, - }) - }, - }, - ], - initialIndexSettings: { - // controls how index are initialized - // only has effects before index are initialize - // you may need to delete your index and recraw after modification - YOUR_INDEX_NAME: { - attributesForFaceting: ['type', 'lang'], - attributesToRetrieve: ['hierarchy', 'content', 'anchor', 'url'], - attributesToHighlight: ['hierarchy', 'hierarchy_camel', 'content'], - attributesToSnippet: ['content:10'], - camelCaseAttributes: ['hierarchy', 'hierarchy_radio', 'content'], - searchableAttributes: [ - 'unordered(hierarchy_radio_camel.lvl0)', - 'unordered(hierarchy_radio.lvl0)', - 'unordered(hierarchy_radio_camel.lvl1)', - 'unordered(hierarchy_radio.lvl1)', - 'unordered(hierarchy_radio_camel.lvl2)', - 'unordered(hierarchy_radio.lvl2)', - 'unordered(hierarchy_radio_camel.lvl3)', - 'unordered(hierarchy_radio.lvl3)', - 'unordered(hierarchy_radio_camel.lvl4)', - 'unordered(hierarchy_radio.lvl4)', - 'unordered(hierarchy_radio_camel.lvl5)', - 'unordered(hierarchy_radio.lvl5)', - 'unordered(hierarchy_radio_camel.lvl6)', - 'unordered(hierarchy_radio.lvl6)', - 'unordered(hierarchy_camel.lvl0)', - 'unordered(hierarchy.lvl0)', - 'unordered(hierarchy_camel.lvl1)', - 'unordered(hierarchy.lvl1)', - 'unordered(hierarchy_camel.lvl2)', - 'unordered(hierarchy.lvl2)', - 'unordered(hierarchy_camel.lvl3)', - 'unordered(hierarchy.lvl3)', - 'unordered(hierarchy_camel.lvl4)', - 'unordered(hierarchy.lvl4)', - 'unordered(hierarchy_camel.lvl5)', - 'unordered(hierarchy.lvl5)', - 'unordered(hierarchy_camel.lvl6)', - 'unordered(hierarchy.lvl6)', - 'content', - ], - distinct: true, - attributeForDistinct: 'url', - customRanking: [ - 'desc(weight.pageRank)', - 'desc(weight.level)', - 'asc(weight.position)', - ], - ranking: [ - 'words', - 'filters', - 'typo', - 'attribute', - 'proximity', - 'exact', - 'custom', - ], - highlightPreTag: '', - highlightPostTag: '', - minWordSizefor1Typo: 3, - minWordSizefor2Typos: 7, - allowTyposOnNumericTokens: false, - minProximity: 1, - ignorePlurals: true, - advancedSyntax: true, - attributeCriteriaComputedByMinProximity: true, - removeWordsIfNoResults: 'allOptional', - }, - }, -}) -``` - -The above `recordProps` is the configuration used for the default theme. You can modify them according to the theme you are using. - -Notice that the `initialIndexSettings.YOUR_INDEX_NAME.attributesForFaceting` fields must include `'lang'` to make this plugin work properly. -::: - -::: tip -If you are not using default theme, or you meet any problems when using docsearch, you can also check the above example crawler config, and ahead to [Algolia Crawler](https://crawler.algolia.com/admin/crawlers/), and edit your config with 'Editor' panel in project sidebar. -::: - -## Options - -### apiKey - -- Type: `string` - -- Required: `true` - -- Details: - - The `apiKey` that you received from the DocSearch team, or generated by yourself. - -- Also see: - - [DocSearch > Options > apiKey](https://docsearch.algolia.com/docs/api#apikey) - -### indexName - -- Type: `string` - -- Required: `true` - -- Details: - - The `indexName` that you received from the DocSearch team, or generated by yourself. - -- Also see: - - [DocSearch > Options > indexName](https://docsearch.algolia.com/docs/api#indexname) - -### appId - -- Type: `string` - -- Required: `true` - -- Details: - - It defines your own application ID. - -- Also see: - - [DocSearch > Options > appId](https://docsearch.algolia.com/docs/api#appid) - -### searchParameters - -- Type: `SearchParameters` - -- Details: - - Parameters of Algolia Search API. - -- Also see: - - [DocSearch > Options > searchParameters](https://docsearch.algolia.com/docs/api/#searchparameters) - - [Algolia > Search API Parameters](https://www.algolia.com/doc/api-reference/search-api-parameters/) - -### placeholder - -- Type: `string` - -- Default: `'Search docs'` - -- Details: - - The placeholder attribute of the search input. - -- Also see: - - [DocSearch > Options > placeholder](https://docsearch.algolia.com/docs/api/#placeholder) - -### disableUserPersonalization - -- Type: `boolean` - -- Default: `false` - -- Details: - - Whether to disable all personalized features: recent searches, favorite searches, etc. - -- Also see: - - [DocSearch > Options > disableUserPersonalization](https://docsearch.algolia.com/docs/api/#disableuserpersonalization) - -### initialQuery - -- Type: `string` - -- Details: - - The initial query when the modal opens. - -- Also see: - - [DocSearch > Options > initialQuery](https://docsearch.algolia.com/docs/api/#initialquery) - -### translations - -- Type: `Partial` - -- Details: - - Allow replacing the default text in the DocSearch button or modal. - -- Also see: - - [DocSearch > Options > translations](https://docsearch.algolia.com/docs/api/#translations) - -### locales - -- Type: `Record` - -- Details: - - Options of this plugin in different locales. - - All other options of this plugin are acceptable in locale config. - -- Example: - -```ts -export default { - plugins: [ - docsearchPlugin({ - appId: '', - apiKey: '', - indexName: '', - locales: { - '/': { - placeholder: 'Search Documentation', - translations: { - button: { - buttonText: 'Search Documentation', - }, - }, - }, - '/zh/': { - placeholder: '搜索文档', - translations: { - button: { - buttonText: '搜索文档', - }, - }, - }, - }, - }), - ], -} -``` - -- Also see: - - [Guide > I18n](../../guide/i18n.md) - -### indexBase - -- Type: `string` - -- Default: [base](../config.md#base) - -- Details: - - The base path of the search index. - - If you are deploying your site to multiple domains, you don't need to submit all of them to DocSearch and generate search index separately. You could choose one of the domains as the _index domain_, and only submit the _index domain_ to Docsearch for crawling search index. Then, you could reuse the search index across all deployments. - - However, if the [base](../config.md#base) of your deployments are different for different domains, you need to set the option to the [base](../config.md#base) of your _index domain_, so that other deployments could reuse the search index correctly. - -### injectStyles - -- Type: `boolean` - -- Default: `true` - -- Details: - - Whether to inject the default styles of DocSearch or not. - - If you think the default styles of DocSearch is not compatible with your site, you can try to override the default styles, or set this option to `false` to totally exclude the default styles. - - When this option is disabled, you need to import your own styles for DocSearch. Also notice that all styles customization in [Styles](#styles) section would be unavailable. - -## Styles - -You can customize styles via CSS variables that provided by [@docsearch/css](https://docsearch.algolia.com/docs/styling): - -```css -:root { - --docsearch-primary-color: rgb(84, 104, 255); - --docsearch-text-color: rgb(28, 30, 33); - --docsearch-spacing: 12px; - --docsearch-icon-stroke-width: 1.4; - --docsearch-highlight-color: var(--docsearch-primary-color); - --docsearch-muted-color: rgb(150, 159, 175); - --docsearch-container-background: rgba(101, 108, 133, 0.8); - --docsearch-logo-color: rgba(84, 104, 255); - - /* modal */ - --docsearch-modal-width: 560px; - --docsearch-modal-height: 600px; - --docsearch-modal-background: rgb(245, 246, 247); - --docsearch-modal-shadow: inset 1px 1px 0 0 rgba(255, 255, 255, 0.5), 0 3px - 8px 0 rgba(85, 90, 100, 1); - - /* searchbox */ - --docsearch-searchbox-height: 56px; - --docsearch-searchbox-background: rgb(235, 237, 240); - --docsearch-searchbox-focus-background: #fff; - --docsearch-searchbox-shadow: inset 0 0 0 2px var(--docsearch-primary-color); - - /* hit */ - --docsearch-hit-height: 56px; - --docsearch-hit-color: rgb(68, 73, 80); - --docsearch-hit-active-color: #fff; - --docsearch-hit-background: #fff; - --docsearch-hit-shadow: 0 1px 3px 0 rgb(212, 217, 225); - - /* key */ - --docsearch-key-gradient: linear-gradient( - -225deg, - rgb(213, 219, 228) 0%, - rgb(248, 248, 248) 100% - ); - --docsearch-key-shadow: inset 0 -2px 0 0 rgb(205, 205, 230), inset 0 0 1px 1px - #fff, 0 1px 2px 1px rgba(30, 35, 90, 0.4); - - /* footer */ - --docsearch-footer-height: 44px; - --docsearch-footer-background: #fff; - --docsearch-footer-shadow: 0 -1px 0 0 rgb(224, 227, 232), 0 -3px 6px 0 rgba(69, 98, 155, 0.12); -} -``` - -## Components - -### Docsearch - -- Details: - - This plugin will register a `` component globally, and you can use it without any props. - - Put this component to where you want to place the docsearch button. For example, default theme puts this component to the end of the navbar. - -::: tip -This component is mainly used for theme development. You don't need to use it directly in most cases. -::: diff --git a/docs/reference/plugin/external-link-icon.md b/docs/reference/plugin/external-link-icon.md deleted file mode 100644 index c57f4374..00000000 --- a/docs/reference/plugin/external-link-icon.md +++ /dev/null @@ -1,87 +0,0 @@ -# external-link-icon - - - -This plugin will add an icon to the external link in your markdown content, i.e. - -This plugin has been integrated into the default theme. - -## Usage - -```bash -npm i -D @vuepress/plugin-external-link-icon@next -``` - -```ts -import { externalLinkIconPlugin } from '@vuepress/plugin-external-link-icon' - -export default { - plugins: [ - externalLinkIconPlugin({ - // options - }), - ], -} -``` - -## Options - -### locales - -- Type: `Record` - -- Details: - - The a11y text of the external link icon in different locales. - - If this option is not specified, it will fallback to default text. - -- Example: - -```ts -export default { - plugins: [ - externalLinkIconPlugin({ - locales: { - '/': { - openInNewWindow: 'open in new window', - }, - '/zh/': { - openInNewWindow: '在新窗口打开', - }, - }, - }), - ], -} -``` - -- Also see: - - [Guide > I18n](../../guide/i18n.md) - -## Frontmatter - -### externalLinkIcon - -- Type: `boolean` - -- Details: - - Whether to append an external link icon to external links in current page. - -## Styles - -You can customize the style of the external link icon via CSS variables: - -@[code css](@vuepress/plugin-external-link-icon/src/client/styles/vars.css) - -## Components - -### ExternalLinkIcon - -- Details: - - This plugin will register a `` component globally, and you can use it without any props. - -::: tip -This component is mainly used for theme development. You don't need to use it directly in most cases. -::: diff --git a/docs/reference/plugin/git.md b/docs/reference/plugin/git.md deleted file mode 100644 index 059c8ab1..00000000 --- a/docs/reference/plugin/git.md +++ /dev/null @@ -1,145 +0,0 @@ -# git - - - -This plugin will collect git information of your pages, including the created and updated time, the contributors, etc. - -The [lastUpdated](../default-theme/config.md#lastupdated) and [contributors](../default-theme/config.md#contributors) of default theme is powered by this plugin. - -This plugin is mainly used to develop themes. You won't need to use it directly in most cases. - -## Usage - -```bash -npm i -D @vuepress/plugin-git@next -``` - -```ts -import { gitPlugin } from '@vuepress/plugin-git' - -export default { - plugins: [ - gitPlugin({ - // options - }), - ], -} -``` - -## Git Repository - -This plugin requires your project to be inside a [Git Repository](https://git-scm.com/book/en/Git-Basics-Getting-a-Git-Repository), so that it can collect information from the commit history. - -You should ensure all commits are available when building your site. For example, CI workflows usually clone your repository with [--depth 1](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt) to avoid fetching all commits, so you should disable the behavior to make this plugin work properly in CI. - -::: warning -This plugin will significantly slow down the speed of data preparation, especially when you have a lot of pages. You can consider disabling this plugin in `dev` mode to get better development experience. -::: - -## Options - -### createdTime - -- Type: `boolean` - -- Default: `true` - -- Details: - - Whether to collect page created time or not. - -### updatedTime - -- Type: `boolean` - -- Default: `true` - -- Details: - - Whether to collect page updated time or not. - -### contributors - -- Type: `boolean` - -- Default: `true` - -- Details: - - Whether to collect page contributors or not. - -## Frontmatter - -### gitInclude - -- Type: `string[]` - -- Details: - - An array of relative paths to be included when calculating page data. - -- Example: - -```md ---- -gitInclude: - - relative/path/to/file1 - - relative/path/to/file2 ---- -``` - -## Page Data - -This plugin will add a `git` field to page data. - -After using this plugin, you can get the collected git information in page data: - -```ts -import type { GitPluginPageData } from '@vuepress/plugin-git' -import { usePageData } from 'vuepress/client' - -export default { - setup() { - const page = usePageData() - console.log(page.value.git) - }, -} -``` - -### git.createdTime - -- Type: `number` - -- Details: - - Unix timestamp in milliseconds of the first commit of the page. - - This attribute would take the minimum of the first commit timestamps of the current page and the files listed in [gitInclude](#gitinclude). - -### git.updatedTime - -- Type: `number` - -- Details: - - Unix timestamp in milliseconds of the last commit of the page. - - This attribute would take the maximum of the last commit timestamps of the current page and the files listed in [gitInclude](#gitinclude). - -### git.contributors - -- Type: `GitContributor[]` - -```ts -interface GitContributor { - name: string - email: string - commits: number -} -``` - -- Details: - - The contributors information of the page. - - This attribute would also include contributors to the files listed in [gitInclude](#gitinclude). diff --git a/docs/reference/plugin/google-analytics.md b/docs/reference/plugin/google-analytics.md deleted file mode 100644 index c35b267d..00000000 --- a/docs/reference/plugin/google-analytics.md +++ /dev/null @@ -1,78 +0,0 @@ -# google-analytics - - - -Integrate [Google Analytics](https://analytics.google.com/) into VuePress. - -This plugin will import [gtag.js](https://developers.google.com/analytics/devguides/collection/gtagjs) for [Google Analytics 4](https://support.google.com/analytics/answer/10089681). - -## Usage - -```bash -npm i -D @vuepress/plugin-google-analytics@next -``` - -```ts -import { googleAnalyticsPlugin } from '@vuepress/plugin-google-analytics' - -export default { - plugins: [ - googleAnalyticsPlugin({ - // options - }), - ], -} -``` - -## Reporting Events - -Google Analytics will [automatically collect some events](https://support.google.com/analytics/answer/9234069), such as `page_view`, `first_visit`, etc. - -So if you only want to collect some basic data of your site, you don't need to do anything else except setting the [Measurement ID](#id) correctly. - -After using this plugin, the global `gtag()` function is available on the `window` object, and you can use it for [custom events reporting](https://developers.google.com/analytics/devguides/collection/ga4/events). - -## Options - -### id - -- Type: `string` - -- Details: - - The Measurement ID of Google Analytics 4, which should start with `'G-'`. - - You can follow the instructions [here](https://support.google.com/analytics/answer/9539598) to find your Measurement ID. Notice the difference between Google Analytics 4 Measurement ID (i.e. "G-" ID) and Universal Analytics Tracking ID (i.e. "UA-" ID). - -- Example: - -```ts -export default { - plugins: [ - googleAnalyticsPlugin({ - id: 'G-XXXXXXXXXX', - }), - ], -} -``` - -### debug - -- Type: `boolean` - -- Details: - - Set to `true` to enable sending events to DebugView. [See more information on DebugView](https://support.google.com/analytics/answer/7201382). - -- Example: - -```ts -export default { - plugins: [ - googleAnalyticsPlugin({ - id: 'G-XXXXXXXXXX', - debug: true, - }), - ], -} -``` diff --git a/docs/reference/plugin/medium-zoom.md b/docs/reference/plugin/medium-zoom.md deleted file mode 100644 index 362dce25..00000000 --- a/docs/reference/plugin/medium-zoom.md +++ /dev/null @@ -1,100 +0,0 @@ -# medium-zoom - - - -Integrate [medium-zoom](https://github.com/francoischalifour/medium-zoom#readme) into VuePress, which can provide the ability to zoom images. - -This plugin has been integrated into the default theme. - -## Usage - -```bash -npm i -D @vuepress/plugin-medium-zoom@next -``` - -```ts -import { mediumZoomPlugin } from '@vuepress/plugin-medium-zoom' - -export default { - plugins: [ - mediumZoomPlugin({ - // options - }), - ], -} -``` - -## Options - -### selector - -- Type: `string` - -- Default: `':not(a) > img'` - -- Details: - - Selector of zoomable images. - - By default this plugin will make all images zoomable except those inside `` tags. - -### delay - -- Type: `number` - -- Default: `500` - -- Details: - - Delay in milliseconds. - - After navigating to a new page, this plugin will make images zoomable with a delay. - -### zoomOptions - -- Type: `Object` - -- Details: - - Options for medium-zoom. - -- Also see: - - [medium-zoom > Options](https://github.com/francoischalifour/medium-zoom#options) - -## Styles - -You can customize most of the zoom styles via [zoomOptions](#zoomoptions), while this plugin also provides some CSS variables for additional customization: - -@[code css](@vuepress/plugin-medium-zoom/src/client/styles/vars.css) - -## Composition API - -### useMediumZoom - -- Details: - - Returns the `Zoom` instance that used by this plugin, so that you can use the instance [methods](https://github.com/francoischalifour/medium-zoom#methods) directly. - - This plugin will make images zoomable after navigating to current page. But if you are going to add new images dynamically, you may need this method to make those new images zoomable, too. - - This plugin adds an extra `refresh` method on the `Zoom` instance, which will call `zoom.detach()` then `zoom.attach()` with the [selector](#selector) as the default parameter. It will help you to refresh the zoomable images for current page. - -- Example: - -```ts -import { nextTick } from 'vue' -import { useMediumZoom } from '@vuepress/plugin-medium-zoom/client' - -export default { - setup() { - const zoom = useMediumZoom() - - // ... do something to add new images in current page - - // then you may need to call `refresh` manually to make those new images zoomable - nextTick(() => { - zoom.refresh() - }) - }, -} -``` diff --git a/docs/reference/plugin/nprogress.md b/docs/reference/plugin/nprogress.md deleted file mode 100644 index 2f501345..00000000 --- a/docs/reference/plugin/nprogress.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: nprogress ---- - - - - - -# nprogress Plugin - - - -Integrate [nprogress](https://github.com/rstacruz/nprogress) into VuePress, which can provide a progress bar when navigating to another page. - -This plugin has been integrated into the default theme. - -## Usage - -```bash -npm i -D @vuepress/plugin-nprogress@next -``` - -```ts -import { nprogressPlugin } from '@vuepress/plugin-nprogress' - -export default { - plugins: [nprogressPlugin()], -} -``` - -## Styles - -You can customize the style of the progress bar via CSS variables: - -@[code css](@vuepress/plugin-nprogress/src/client/styles/vars.css) diff --git a/docs/reference/plugin/palette.md b/docs/reference/plugin/palette.md deleted file mode 100644 index a5a5ecb8..00000000 --- a/docs/reference/plugin/palette.md +++ /dev/null @@ -1,203 +0,0 @@ -# palette - - - -Provide palette support for your theme. - -This plugin is mainly used to develop themes, and has been integrated into the default theme. You won't need to use it directly in most cases. - -For theme authors, this plugin will help you to provide styles customization for users. - -## Usage - -```bash -npm i -D @vuepress/plugin-palette@next -``` - -```ts -import { palettePlugin } from '@vuepress/plugin-palette' - -export default { - plugins: [ - palettePlugin({ - // options - }), - ], -} -``` - -## Palette and Style - -This plugin will provide a `@vuepress/plugin-palette/palette` (palette file) and a `@vuepress/plugin-palette/style` (style file) to be imported in your theme styles. - -The palette file is used for defining style variables, so it's likely to be imported at the beginning of your theme styles. For example, users can define [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties), [SASS variables](https://sass-lang.com/documentation/variables), [LESS variables](http://lesscss.org/features/#variables-feature) or [Stylus variables](https://stylus-lang.com/docs/variables.html) in the palette, and then you can use those variables in your theme styles. - -The style file is used for overriding the default styles or adding extra styles, so it's likely to be imported at the end of your theme styles. - -## Usage - -Use this plugin in your theme, assuming you are using SASS: - -```ts -export default { - // ... - plugins: [palettePlugin({ preset: 'sass' })], -} -``` - -### Usage of Palette - -Import the plugin's palette file where your theme needs to use the corresponding variables, such as in the `Layout.vue` file: - -```vue - - - -``` - -Then users can customize variables in `.vuepress/styles/palette.scss`: - -```scss -$color: green; -``` - -### Usage of Style - -Import the plugin's style file after your theme's styles, for example, in the `clientConfigFile`: - -```ts -// import your theme's style file -import 'path/to/your/theme/style' -// import the plugin's style file -import '@vuepress/plugin-palette/style' -``` - -Then users can add extra styles in `.vuepress/styles/index.scss` and override the default styles of your theme: - -```scss -h1 { - font-size: 2.5rem; -} -``` - -## Options - -### preset - -- Type: `'css' | 'sass' | 'less' | 'stylus'` - -- Default: `'css'` - -- Details: - - Set preset for other options. - - If you don't need advanced customization of the plugin, it's recommended to only set this option and omit other options. - -### userPaletteFile - -- Type: `string` - -- Default: - - - css: `'.vuepress/styles/palette.css'` - - sass: `'.vuepress/styles/palette.scss'` - - less: `'.vuepress/styles/palette.less'` - - stylus: `'.vuepress/styles/palette.styl'` - -- Details: - - File path of the user palette file, relative to source directory. - - The default value depends on the [preset](#preset) option. - - The file is where users define style variables, and it's recommended to keep the default file path as a convention. - -### tempPaletteFile - -- Type: `string` - -- Default: - - - css: `'styles/palette.css'` - - sass: `'styles/palette.scss'` - - less: `'styles/palette.less'` - - stylus: `'styles/palette.styl'` - -- Details: - - File path of the generated palette temp file, relative to temp directory. - - The default value depends on the [preset](#preset) option. - - You should import the palette file via `'@vuepress/plugin-palette/palette'` alias, so you don't need to change this option in most cases. - -### userStyleFile - -- Type: `string` - -- Default: - - - css: `'.vuepress/styles/index.css'` - - sass: `'.vuepress/styles/index.scss'` - - less: `'.vuepress/styles/index.less'` - - stylus: `'.vuepress/styles/index.styl'` - -- Details: - - File path of the user style file, relative to source directory. - - The default value depends on the [preset](#preset) option. - - The file is where users override default styles or add extra styles, and it's recommended to keep the default file path as a convention. - -### tempStyleFile - -- Type: `string` - -- Default: - - - css: `'styles/index.css'` - - sass: `'styles/index.scss'` - - less: `'styles/index.less'` - - stylus: `'styles/index.styl'` - -- Details: - - File path of the generated style temp file, relative to temp directory. - - The default value depends on the [preset](#preset) option. - - You should import the style file via `'@vuepress/plugin-palette/style'` alias, so you don't need to change this option in most cases. - -### importCode - -- Type: `(filePath: string) => string` - -- Default: - - - css: `` (filePath) => `@import '${filePath}';\n` `` - - sass: `` (filePath) => `@forward 'file:///${filePath}';\n` `` - - less: `` (filePath) => `@import '${filePath}';\n` `` - - stylus: `` (filePath) => `@require '${filePath}';\n` `` - -- Details: - - Function to generate import code. - - The default value depends on the [preset](#preset) option. - - This option is used for generating [tempPaletteFile](#temppalettefile) and [tempStyleFile](#tempstylefile), and you don't need to change this option in most cases. diff --git a/docs/reference/plugin/prismjs.md b/docs/reference/plugin/prismjs.md deleted file mode 100644 index d72625f2..00000000 --- a/docs/reference/plugin/prismjs.md +++ /dev/null @@ -1,43 +0,0 @@ -# prismjs - - - -This plugin will enable syntax highlighting for markdown code fence with [Prism.js](https://prismjs.com/). - -This plugin has been integrated into the default theme. - -Notice that this plugin would only tokenize the code fence without adding styles. When using it with a custom theme, you may need to choose and import Prism.js style theme yourself. - -## Usage - -```bash -npm i -D @vuepress/plugin-prismjs@next -``` - -```ts -import { prismjsPlugin } from '@vuepress/plugin-prismjs' - -export default { - plugins: [ - prismjsPlugin({ - // options - }), - ], -} -``` - -## Options - -### preloadLanguages - -- Type: `string[]` - -- Default: `['markdown', 'jsdoc', 'yaml']` - -- Details: - - Languages to preload. - - By default, languages will be loaded on demand when parsing markdown files. - - However, Prism.js has [some potential issues](https://github.com/PrismJS/prism/issues/2716) about loading languages dynamically. To avoid them, you can preload languages via this option. diff --git a/docs/reference/plugin/pwa-popup.md b/docs/reference/plugin/pwa-popup.md deleted file mode 100644 index f305e526..00000000 --- a/docs/reference/plugin/pwa-popup.md +++ /dev/null @@ -1,72 +0,0 @@ -# pwa-popup - - - -Provide a popup component for users to activate the new PWA service worker manually. - -This plugin must be used together with [pwa plugin](./pwa.md), and the `skipWaiting` option must not be set to `true`. - -When the new service worker is ready, a popup will appear in the right bottom of the page to ask users to activate the waiting service worker. - -## Usage - -```bash -npm i -D @vuepress/plugin-pwa-popup@next -``` - -```ts -import { pwaPlugin } from '@vuepress/plugin-pwa' -import { pwaPopupPlugin } from '@vuepress/plugin-pwa-popup' - -export default { - plugins: [ - pwaPlugin(), - pwaPopupPlugin({ - // options - }), - ], -} -``` - -## Options - -### locales - -- Type: `Record` - -- Details: - - The messages of the popup in different locales. - - If this option is not specified, it will fallback to default messages. - -- Example: - -```ts -export default { - plugins: [ - pwaPlugin(), - pwaPopupPlugin({ - locales: { - '/': { - message: 'New content is available.', - buttonText: 'Refresh', - }, - '/zh/': { - message: '发现新内容可用', - buttonText: '刷新', - }, - }, - }), - ], -} -``` - -- Also see: - - [Guide > I18n](../../guide/i18n.md) - -## Styles - -You can customize the style of the popup via CSS variables: - -@[code css](@vuepress/plugin-pwa-popup/src/client/styles/vars.css) diff --git a/docs/reference/plugin/pwa.md b/docs/reference/plugin/pwa.md deleted file mode 100644 index e94f7697..00000000 --- a/docs/reference/plugin/pwa.md +++ /dev/null @@ -1,173 +0,0 @@ -# pwa - - - -Make your VuePress site a [Progressive Web Application (PWA)](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps). - -This plugin uses [workbox-build](https://developers.google.com/web/tools/workbox/modules/workbox-build) to generate service worker file, and uses [register-service-worker](https://github.com/yyx990803/register-service-worker) to register service worker. - -## Usage - -```bash -npm i -D @vuepress/plugin-pwa@next -``` - -```ts -import { pwaPlugin } from '@vuepress/plugin-pwa' - -export default { - plugins: [ - pwaPlugin({ - // options - }), - ], -} -``` - -## Web App Manifests - -To make your website fully compliant with PWA, you need to create a [Web app manifests](https://developer.mozilla.org/en-US/docs/Web/Manifest) file and set the icons, colors, etc. for your PWA. - -You need to put your manifest file and icons into the [public files directory](../../guide/assets.md#public-files). In the following example, we assume that you are using the default public directory `.vuepress/public`. - -1. Create manifest file - -Typically `.vuepress/public/manifest.webmanifest`: - -```json -{ - "name": "VuePress", - "short_name": "VuePress", - "description": "Vue-powered Static Site Generator", - "start_url": "/index.html", - "display": "standalone", - "background_color": "#fff", - "theme_color": "#3eaf7c", - "icons": [ - { - "src": "/images/icons/android-chrome-192x192.png", - "sizes": "192x192", - "type": "image/png" - }, - { - "src": "/images/icons/android-chrome-384x384.png", - "sizes": "384x384", - "type": "image/png" - } - ] -} -``` - -2. Generate PWA icons - -To make your PWA more accessible, you need to generate some icons, and put them inside the public directory. - -Make sure the path of icons matches the `icons` field in your manifest file: - -- `.vuepress/public/images/icons/android-chrome-192x192.png` -- `.vuepress/public/images/icons/android-chrome-384x384.png` - -::: tip -Some tools can help to do that. For example, [Favicon Generator](https://realfavicongenerator.net/) would help you to generate icons together with a sample manifest file. -::: - -3. Set tags in head - -You also need to set some tags via [head](../config.md#head) option to [deploy the manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest#deploying_a_manifest_with_the_link_tag): - -```ts -export default { - head: [ - ['link', { rel: 'manifest', href: '/manifest.webmanifest' }], - ['meta', { name: 'theme-color', content: '#3eaf7c' }], - // ...other tags - ], -} -``` - -## Options - -This plugin accepts all parameters of workbox-build's [generateSW method](https://developers.google.com/web/tools/workbox/reference-docs/latest/module-workbox-build#.generateSW) in its options, except `globDirectory` and `swDest`. - -For example, you can set `skipWaiting: true` to auto activate the new service worker once it is ready: - -```ts -export default { - plugins: [ - pwaPlugin({ - skipWaiting: true, - }), - ], -} -``` - -But if you omit `skipWaiting` or set it to `false`, you have to activate the new service worker manually: - -- For users, you can use our [pwa-popup](./pwa-popup.md) plugin together. -- For developers, you can use our [composition API](#composition-api) to take control of the service worker behavior. - -### serviceWorkerFilename - -- Type: `string` - -- Default: `'service-worker.js'` - -- Details: - - File path of the generated service worker file, which is relative to the [dest](../config.md#dest) directory. - - The service worker file will only be generated in `build` mode. - -## Composition API - -### usePwaEvent - -- Details: - - Returns the event emitter of this plugin. - - You can add listener function to events that provided by [register-service-worker](https://github.com/yyx990803/register-service-worker). - -- Example: - -```ts -import { usePwaEvent } from '@vuepress/plugin-pwa/client' - -export default { - setup() { - const event = usePwaEvent() - event.on('ready', (registration) => { - console.log('Service worker is active.') - }) - }, -} -``` - -### useSkipWaiting - -- Parameters: - -| Parameter | Type | Description | -| ------------ | --------------------------- | -------------------------------------------------------- | -| registration | `ServiceWorkerRegistration` | The registration of the service worker you want activate | - -- Details: - - Call [skipWaiting()](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerGlobalScope/skipWaiting) to activate the waiting service worker. - -- Example: - -```ts -import { usePwaEvent, useSkipWaiting } from '@vuepress/plugin-pwa/client' - -export default { - setup() { - const event = usePwaEvent() - event.on('updated', (registration) => { - console.log('The waiting service worker is available.') - // activate the waiting service worker - useSkipWaiting(registration) - }) - }, -} -``` diff --git a/docs/reference/plugin/register-components.md b/docs/reference/plugin/register-components.md deleted file mode 100644 index 45158608..00000000 --- a/docs/reference/plugin/register-components.md +++ /dev/null @@ -1,135 +0,0 @@ -# register-components - - - -Register Vue components from component files or directory automatically. - -## Usage - -```bash -npm i -D @vuepress/plugin-register-components@next -``` - -```ts -import { registerComponentsPlugin } from '@vuepress/plugin-register-components' - -export default { - plugins: [ - registerComponentsPlugin({ - // options - }), - ], -} -``` - -## Options - -### components - -- Type: `Record` - -- Default: `{}` - -- Details: - - An object that defines name of components and their corresponding file path. - - The key will be used as the component name, and the value is an absolute path of the component file. - - If the component name from this option conflicts with [componentsDir](#componentsdir) option, this option will have a higher priority. - -- Example: - -```ts -import { getDirname, path } from 'vuepress/utils' - -const __dirname = getDirname(import.meta.url) - -export default { - plugins: [ - registerComponentsPlugin({ - components: { - FooBar: path.resolve(__dirname, './components/FooBar.vue'), - }, - }), - ], -} -``` - -### componentsDir - -- Type: `string | null` - -- Default: `null` - -- Details: - - Absolute path to the components directory. - - Files in this directory which are matched with [componentsPatterns](#componentspatterns) will be registered as Vue components automatically. - -- Example: - -```ts -import { getDirname, path } from 'vuepress/utils' - -const __dirname = getDirname(import.meta.url) - -export default { - plugins: [ - registerComponentsPlugin({ - componentsDir: path.resolve(__dirname, './components'), - }), - ], -} -``` - -Components directory: - -```bash -components -├─ FooBar.vue -└─ Baz.vue -``` - -Components will be registered like this: - -```ts -import { defineAsyncComponent } from 'vue' - -app.component( - 'FooBar', - defineAsyncComponent(() => import('/path/to/components/FooBar.vue')), -) - -app.component( - 'Baz', - defineAsyncComponent(() => import('/path/to/components/Baz.vue')), -) -``` - -### componentsPatterns - -- Type: `string[]` - -- Default: `['**/*.vue']` - -- Details: - - Patterns to match component files using [globby](https://github.com/sindresorhus/globby). - - The patterns are relative to [componentsDir](#componentsdir). - -### getComponentName - -- Type: `(filename: string) => string` - -- Default: `(filename) => path.trimExt(filename.replace(/\/|\\/g, '-'))` - -- Details: - - A function to get component name from the filename. - - It will only take effect on the files in the [componentsDir](#componentsdir) which are matched with the [componentsPatterns](#componentspatterns). - - Notice that the `filename` is a filepath relative to [componentsDir](#componentsdir). diff --git a/docs/reference/plugin/search.md b/docs/reference/plugin/search.md deleted file mode 100644 index f563b8a7..00000000 --- a/docs/reference/plugin/search.md +++ /dev/null @@ -1,166 +0,0 @@ -# search - - - -Provide local search to your documentation site. - -::: tip -Default theme will add search box to the navbar once you configure this plugin correctly. - -This plugin may not be used directly in other themes, so you'd better refer to the documentation of your theme for more details. -::: - -## Usage - -```bash -npm i -D @vuepress/plugin-search@next -``` - -```ts -import { searchPlugin } from '@vuepress/plugin-search' - -export default { - plugins: [ - searchPlugin({ - // options - }), - ], -} -``` - -## Local Search Index - -This plugin will generate search index from your pages locally, and load the search index file when users enter your site. In other words, this is a lightweight built-in search which does not require any external requests. - -However, when your site has a large number of pages, the size of search index file would be very large, which could slow down the page loading speed. In this case, we recommend you to use a more professional solution - [docsearch](./docsearch.md). - -## Options - -### locales - -- Type: `Record` - -- Details: - - The text of the search box in different locales. - - If this option is not specified, it will fallback to default text. - -- Example: - -```ts -export default { - plugins: [ - searchPlugin({ - locales: { - '/': { - placeholder: 'Search', - }, - '/zh/': { - placeholder: '搜索', - }, - }, - }), - ], -} -``` - -- Also see: - - [Guide > I18n](../../guide/i18n.md) - -### hotKeys - -- Type: `(string | HotKeyOptions)[]` - -@[code ts](@vuepress/plugin-search/src/shared/hotKey.ts) - -- Default: `['s', '/']` - -- Details: - - Specify the [event.key](http://keycode.info/) of the hotkeys. - - When hotkeys are pressed, the search box input will be focused. - - Set to an empty array to disable hotkeys. - -### maxSuggestions - -- Type: `number` - -- Default: `5` - -- Details: - - Specify the maximum number of search results. - -### isSearchable - -- Type: `(page: Page) => boolean` - -- Default: `() => true` - -- Details: - - A function to determine whether a page should be included in the search index. - - - Return `true` to include the page. - - Return `false` to exclude the page. - -- Example: - -```ts -export default { - plugins: [ - searchPlugin({ - // exclude the homepage - isSearchable: (page) => page.path !== '/', - }), - ], -} -``` - -### getExtraFields - -- Type: `(page: Page) => string[]` - -- Default: `() => []` - -- Details: - - A function to add extra fields to the search index of a page. - - By default, this plugin will use page title and headers as the search index. This option could help you to add more searchable fields. - -- Example: - -```ts -export default { - plugins: [ - searchPlugin({ - // allow searching the `tags` frontmatter - getExtraFields: (page) => page.frontmatter.tags ?? [], - }), - ], -} -``` - -## Styles - -You can customize the style of the search box via CSS variables: - -@[code css](@vuepress/plugin-search/src/client/styles/vars.css) - -## Components - -### SearchBox - -- Details: - - This plugin will register a `` component globally, and you can use it without any props. - - Put this component to where you want to place the search box. For example, default theme puts this component to the end of the navbar. - -::: tip -This component is mainly used for theme development. You don't need to use it directly in most cases. -::: diff --git a/docs/reference/plugin/shiki.md b/docs/reference/plugin/shiki.md deleted file mode 100644 index 46dabd29..00000000 --- a/docs/reference/plugin/shiki.md +++ /dev/null @@ -1,75 +0,0 @@ -# shiki - - - -This plugin will enable syntax highlighting for markdown code fence with [Shiki](https://shiki.matsu.io/) ([Shikiji](https://shikiji.netlify.app/)). - -::: tip -[Shiki](https://shiki.matsu.io/) is the syntax highlighter being used by VSCode. It has higher fidelity, but it could be slower than [Prism.js](https://prismjs.com/), especially when you have a lot of code blocks. - -You could consider disabling this plugin in `dev` mode to get better development experience. -::: - -## Usage - -```bash -npm i -D @vuepress/plugin-shiki@next -``` - -```ts -import { shikiPlugin } from '@vuepress/plugin-shiki' - -export default { - plugins: [ - shikiPlugin({ - // options - langs: ['ts', 'json', 'vue', 'md', 'bash', 'diff'], - }), - ], -} -``` - -## Options - -### langs - -- Type: `ShikiLang[]` - -- Details: - - Languages of code blocks to be parsed by shikiji. - - This option will be forwarded to `getHighlighter()` method of shikiji. - - You need to provide the languages list you are using explicitly, otherwise shikiji won't load any languages. - -- Also see: - - [shikiji > Languages](https://shikiji.netlify.app/languages) - -### theme - -- Type: `ShikiTheme` - -- Default: `'nord'` - -- Details: - - Theme of shikiji. - - This option will be forwarded to `codeToHtml()` method of shikiji. - -- Also see: - - [shikiji > Themes](https://shikiji.netlify.app/themes) - -### themes - -- Type: `Record<'dark' | 'light', ShikiTheme>` - -- Details: - - Dark / Light Dual themes of shikiji. - - This option will be forwarded to `codeToHtml()` method of shikiji. - -- Also see: - - [shikiji > Dual Themes](https://shikiji.netlify.app/guide/dual-themes) diff --git a/docs/reference/plugin/theme-data.md b/docs/reference/plugin/theme-data.md deleted file mode 100644 index ecf2ea5a..00000000 --- a/docs/reference/plugin/theme-data.md +++ /dev/null @@ -1,118 +0,0 @@ -# theme-data - - - -Provide client data for your theme, with VuePress [i18n](../../guide/i18n.md) support. - -This plugin is mainly used to develop themes, and has been integrated into the default theme. You won't need to use it directly in most cases. - -For theme authors, this plugin will help you to use the same i18n mechanism as VuePress and the default theme. But if you don't want to provide i18n support, or you want to implement in your own way, you don't need this plugin. - -## Usage - -```bash -npm i -D @vuepress/plugin-theme-data@next -``` - -```ts -import { themeDataPlugin } from '@vuepress/plugin-theme-data' - -export default { - plugins: [ - themeDataPlugin({ - // options - }), - ], -} -``` - -## Options - -### themeData - -- Type: `ThemeData` - -- Default: `{}` - -- Details: - - The theme data object that you want to use in client side. - - You can provide theme data in Node side via this option, and use it in client side via [useThemeData](#useThemeData) and [useThemeLocaleData](#useThemeLocaleData). - -- Example: - -```ts -export default { - plugins: [ - themeDataPlugin({ - themeData: { - foo: 'foo', - locales: { - '/zh/': { - foo: 'zh-foo', - }, - }, - }, - }), - ], -} -``` - -::: warning -The theme data object will be processed by `JSON.stringify()` before forwarding to client side, so you should ensure that you are providing a JSON-friendly object. -::: - -## Composition API - -### useThemeData - -- Details: - - Returns the theme data ref object. - - The value is provided by [themeData](#themeData) option. - -- Example: - -```ts -import { useThemeData } from '@vuepress/plugin-theme-data/client' -import type { ThemeData } from '@vuepress/plugin-theme-data/client' - -type MyThemeData = ThemeData<{ - foo: string -}> - -export default { - setup() { - const themeData = useThemeData() - console.log(themeData.value) - }, -} -``` - -### useThemeLocaleData - -- Details: - - Returns the theme data ref object in current locale. - - The properties of current locale has been merged into the root-level properties. - -- Example: - -```ts -import { useThemeLocaleData } from '@vuepress/plugin-theme-data/client' -import type { ThemeData } from '@vuepress/plugin-theme-data/client' - -type MyThemeData = ThemeData<{ - foo: string -}> - -export default { - setup() { - const themeLocaleData = useThemeLocaleData() - console.log(themeLocaleData.value) - }, -} -``` diff --git a/docs/reference/plugin/toc.md b/docs/reference/plugin/toc.md deleted file mode 100644 index 82ffdf85..00000000 --- a/docs/reference/plugin/toc.md +++ /dev/null @@ -1,172 +0,0 @@ -# toc - - - -This plugin will provide a table-of-contents (TOC) component. - -## Usage - -```bash -npm i -D @vuepress/plugin-toc@next -``` - -```ts -import { tocPlugin } from '@vuepress/plugin-toc' - -export default { - plugins: [ - tocPlugin({ - // options - }), - ], -} -``` - -## Differences with Markdown TOC Syntax - -Similar to the [Table of Contents Markdown Syntax](../../guide/markdown.md#table-of-contents), the TOC component that provided by this plugin could be used in your markdown content directly: - -```md - - -[[toc]] - - - -``` - -Both of them can be pre-rendered correctly in build mode. However, there are some differences between them. - -The markdown syntax `[[toc]]` could only be used in markdown files. It is parsed by markdown-it, and the generated TOC is static content. - -The component `` could be used in both markdown files and vue files. It is loaded by vue, and the generated TOC is a vue component. - -This plugin could work together with [@vuepress/plugin-active-header-links](./active-header-links.md) by setting the [headerLinkSelector](./active-header-links.md#headerlinkselector) to match the `linkClass` option. When the page scroll to a certain header anchor, this corresponding link will be added `linkActiveClass` class name. - -Therefore, this plugin is more useful for theme developers. - -## Options - -### componentName - -- Type: `string` - -- Default: `'Toc'` - -- Details: - - Specify the name of the TOC component. - -### defaultPropsOptions - -- Type: `Partial` - -- Default: `{}` - -- Details: - - Override the default values of the component [options](#options-1) prop. - -## Component Props - -The TOC component also accepts props for customization. - -```vue - -``` - -### headers - -- Type: `PageHeader[]` - -```ts -interface PageHeader { - level: number - title: string - slug: string - children: PageHeader[] -} -``` - -- Details: - - Specify the headers array to render. - - If this prop is not specified, the headers of current page will be used. - -### options - -- Type: `Partial` - -```ts -interface TocPropsOptions { - containerTag: string - containerClass: string - listClass: string - itemClass: string - linkTag: 'a' | 'RouterLink' - linkClass: string - linkActiveClass: string - linkChildrenActiveClass: string -} -``` - -- Default: - - Following default values can be overridden by [defaultPropsOptions](#defaultpropsoptions). - -```ts -const defaultOptions = { - containerTag: 'nav', - containerClass: 'vuepress-toc', - listClass: 'vuepress-toc-list', - itemClass: 'vuepress-toc-item', - linkTag: 'RouterLink', - linkClass: 'vuepress-toc-link', - linkActiveClass: 'active', - linkChildrenActiveClass: 'active', -} -``` - -- Details: - - Customize the TOC component. - - If the `containerTag` is set to an empty string `''`, the `