+
+
+
diff --git a/docs/.vitepress/theme/documate.vue b/docs/.vitepress/theme/documate.vue
new file mode 100644
index 00000000..d89e2f40
--- /dev/null
+++ b/docs/.vitepress/theme/documate.vue
@@ -0,0 +1,5 @@
+
+
+
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
new file mode 100644
index 00000000..8c9aecc6
--- /dev/null
+++ b/docs/.vitepress/theme/index.ts
@@ -0,0 +1,13 @@
+// .vitepress/theme/index.js
+import { h } from 'vue'
+import DefaultTheme from 'vitepress/theme'
+import AdComponent from './AdComponent.vue'
+
+export default {
+ ...DefaultTheme,
+ Layout() {
+ return h(DefaultTheme.Layout, null, {
+ 'doc-before': () => h(AdComponent)
+ })
+ }
+}
diff --git a/docs/guide/asset-handling.md b/docs/guide/asset-handling.md
index 2f62569d..7d2ce57a 100644
--- a/docs/guide/asset-handling.md
+++ b/docs/guide/asset-handling.md
@@ -26,25 +26,6 @@ Assets placed in `public` will be copied to the root of the output directory as-
Note that you should reference files placed in `public` using root absolute path - for example, `public/icon.png` should always be referenced in source code as `/icon.png`.
-There is one exception to this: if you have an HTML page in `public` and link to it from the main site, the router will yield a 404 by default. To get around this, VitePress provides a `pathname://` protocol which allows you to link to another page in the same domain as if the link is external. Compare these two links:
-
-- [/pure.html](/pure.html)
--
-
-Note that `pathname://` is only supported in Markdown links. Also, `pathname://` will open the link in a new tab by default. You can use `target="_self"` instead to open it in the same tab:
-
-**Input**
-
-```md
-[Link to pure.html](/pure.html){target="_self"}
-
-
-```
-
-**Output**
-
-[Link to pure.html](/pure.html){target="_self"}
-
## Base URL
If your site is deployed to a non-root URL, you will need to set the `base` option in `.vitepress/config.js`. For example, if you plan to deploy your site to `https://foo.github.io/bar/`, then `base` should be set to `'/bar/'` (it should always start and end with a slash).
diff --git a/docs/guide/data-loading.md b/docs/guide/data-loading.md
index 6d54b2ca..2a356c21 100644
--- a/docs/guide/data-loading.md
+++ b/docs/guide/data-loading.md
@@ -13,7 +13,7 @@ A data loader file must end with either `.data.js` or `.data.ts`. The file shoul
export default {
load() {
return {
- data: 'hello'
+ hello: 'world'
}
}
}
@@ -35,7 +35,7 @@ Output:
```json
{
- "data": "hello"
+ "hello": "world"
}
```
@@ -99,7 +99,8 @@ The loaded data will be an array with the type of `ContentData[]`:
```ts
interface ContentData {
- // mapped absolute URL for the page. e.g. /posts/hello.html
+ // mapped URL for the page. e.g. /posts/hello.html (does not include base)
+ // manually iterate or use custom `transform` to normalize the paths
url: string
// frontmatter data of the page
frontmatter: Record
diff --git a/docs/guide/deploy.md b/docs/guide/deploy.md
index 679d9ff9..baf52b35 100644
--- a/docs/guide/deploy.md
+++ b/docs/guide/deploy.md
@@ -111,7 +111,7 @@ Set up a new project and change these settings using your dashboard:
- **Build Command:** `npm run docs:build`
- **Output Directory:** `docs/.vitepress/dist`
-- **Node Version:** `16` (or above, by default it usually will be 14 or 16, but on Cloudflare Pages the default is still 12, so you may need to [change that](https://developers.cloudflare.com/pages/platform/build-configuration/))
+- **Node Version:** `18` (or above)
::: warning
Don't enable options like _Auto Minify_ for HTML code. It will remove comments from output which have meaning to Vue. You may see hydration mismatch errors if they get removed.
@@ -157,6 +157,7 @@ Don't enable options like _Auto Minify_ for HTML code. It will remove comments f
with:
fetch-depth: 0 # Not needed if lastUpdated is not enabled
# - uses: pnpm/action-setup@v2 # Uncomment this if you're using pnpm
+ # - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun
- name: Setup Node
uses: actions/setup-node@v3
with:
@@ -165,9 +166,11 @@ Don't enable options like _Auto Minify_ for HTML code. It will remove comments f
- name: Setup Pages
uses: actions/configure-pages@v3
- name: Install dependencies
- run: npm ci # or pnpm install / yarn install
+ run: npm ci # or pnpm install / yarn install / bun install
- name: Build with VitePress
- run: npm run docs:build # or pnpm docs:build / yarn docs:build
+ run: |
+ npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build
+ touch docs/.vitepress/dist/.nojekyll
- name: Upload artifact
uses: actions/upload-pages-artifact@v2
with:
@@ -202,7 +205,7 @@ Don't enable options like _Auto Minify_ for HTML code. It will remove comments f
2. Create a file named `.gitlab-ci.yml` in the root of your project with the content below. This will build and deploy your site whenever you make changes to your content:
```yaml
- image: node:16
+ image: node:18
pages:
cache:
paths:
diff --git a/docs/guide/extending-default-theme.md b/docs/guide/extending-default-theme.md
index 332fa971..e58981bf 100644
--- a/docs/guide/extending-default-theme.md
+++ b/docs/guide/extending-default-theme.md
@@ -1,3 +1,7 @@
+---
+outline: deep
+---
+
# Extending the Default Theme
VitePress' default theme is optimized for documentation, and can be customized. Consult the [Default Theme Config Overview](../reference/default-theme-config) for a comprehensive list of options.
@@ -29,8 +33,8 @@ export default DefaultTheme
```css
/* .vitepress/theme/custom.css */
:root {
- --vp-c-brand: #646cff;
- --vp-c-brand-light: #747bff;
+ --vp-c-brand-1: #646cff;
+ --vp-c-brand-2: #747bff;
}
```
@@ -94,6 +98,7 @@ export default {
// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
+/** @type {import('vitepress').Theme} */
export default {
extends: DefaultTheme,
enhanceApp(ctx) {
@@ -103,6 +108,21 @@ export default {
}
```
+If you're using TypeScript:
+```ts
+// .vitepress/theme/index.ts
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+
+export default {
+ extends: DefaultTheme,
+ async enhanceApp({ app }) {
+ // register your custom global components
+ ctx.app.component('MyGlobalComponent' /* ... */)
+ }
+} satisfies Theme
+```
+
Since we are using Vite, you can also leverage Vite's [glob import feature](https://vitejs.dev/guide/features.html#glob-import) to auto register a directory of components.
## Layout Slots
@@ -195,6 +215,102 @@ Full list of slots available in the default theme layout:
- `nav-screen-content-before`
- `nav-screen-content-after`
+## Using View Transitions API
+
+### On Appearance Toggle
+
+You can extend the default theme to provide a custom transition when the color mode is toggled. An example:
+
+```vue
+
+
+
+
+
+
+
+
+
+```
+
+Result (**warning!**: flashing colors, sudden movements, bright lights):
+
+
+Demo
+
+
+
+
+
+Refer [Chrome Docs](https://developer.chrome.com/docs/web-platform/view-transitions/) from more details on view transitions.
+
+### On Route Change
+
+Coming soon.
+
## Overriding Internal Components
You can use Vite's [aliases](https://vitejs.dev/config/shared-options.html#resolve-alias) to replace default theme components with your custom ones:
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index d1714f28..b557c7ff 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -8,7 +8,7 @@ You can try VitePress directly in your browser on [StackBlitz](https://vitepress
### Prerequisites
-- [Node.js](https://nodejs.org/) version 16 or higher.
+- [Node.js](https://nodejs.org/) version 18 or higher.
- Terminal for accessing VitePress via its command line interface (CLI).
- Text Editor with [Markdown](https://en.wikipedia.org/wiki/Markdown) syntax support.
- [VSCode](https://code.visualstudio.com/) is recommended, along with the [official Vue extension](https://marketplace.visualstudio.com/items?itemName=Vue.volar).
@@ -18,17 +18,21 @@ VitePress can be used on its own, or be installed into an existing project. In b
::: code-group
```sh [npm]
-$ npm install -D vitepress
+$ npm add -D vitepress
```
```sh [pnpm]
-$ pnpm add -D vitepress@latest
+$ pnpm add -D vitepress
```
```sh [yarn]
$ yarn add -D vitepress
```
+```sh [bun]
+$ bun add -D vitepress
+```
+
:::
::: details Getting missing peer deps warnings?
@@ -47,6 +51,12 @@ If using PNPM, you will notice a missing peer warning for `@docsearch/js`. This
:::
+::: tip NOTE
+
+VitePress is an ESM-only package. Don't use `require()` to import it, and make sure your nearest `package.json` contains `"type": "module"`, or change the file extension of your relevant files like `.vitepress/config.js` to `.mjs`/`.mts`. Refer to [Vite's troubleshooting guide](http://vitejs.dev/guide/troubleshooting.html#this-package-is-esm-only) for more details. Also, inside async CJS contexts, you can use `await import('vitepress')` instead.
+
+:::
+
### Setup Wizard
VitePress ships with a command line setup wizard that will help you scaffold a basic project. After installation, start the wizard by running:
@@ -61,13 +71,15 @@ $ npx vitepress init
$ pnpm dlx vitepress init
```
+```sh [bun]
+$ bunx vitepress init
+```
+
:::
You will be greeted with a few simple questions:
-
-
-
+<<< @/snippets/init.ansi
::: tip Vue as Peer Dependency
If you intend to perform customization that uses Vue components or APIs, you should also explicitly install `vue` as a peer dependency.
@@ -155,6 +167,10 @@ $ pnpm run docs:dev
$ yarn docs:dev
```
+```sh [bun]
+$ bun run docs:dev
+```
+
:::
Instead of npm scripts, you can also invoke VitePress directly with:
@@ -169,6 +185,10 @@ $ npx vitepress dev docs
$ pnpm exec vitepress dev docs
```
+```sh [bun]
+$ bunx vitepress dev docs
+```
+
:::
More command line usage is documented in the [CLI Reference](../reference/cli).
diff --git a/docs/guide/markdown.md b/docs/guide/markdown.md
index e20e864f..1541f11d 100644
--- a/docs/guide/markdown.md
+++ b/docs/guide/markdown.md
@@ -206,6 +206,25 @@ console.log('Hello, VitePress!')
```
:::
+Also, you may set custom titles globally by adding the following content in site config, helpful if not writing in English:
+
+```ts
+// config.ts
+export default defineConfig({
+ // ...
+ markdown: {
+ container: {
+ tipLabel: '提示',
+ warningLabel: '警告',
+ dangerLabel: '危险',
+ infoLabel: '信息',
+ detailsLabel: '详细信息'
+ }
+ }
+ // ...
+})
+```
+
### `raw`
This is a special container that can be used to prevent style and router conflicts with VitePress. This is especially useful when you're documenting component libraries. You might also wanna check out [whyframe](https://whyframe.dev/docs/integrations/vitepress) for better isolation.
@@ -220,32 +239,29 @@ Wraps in a
`vp-raw` class can be directly used on elements too. Style isolation is currently opt-in:
-::: details
-
-- Install required deps with your preferred package manager:
+- Install `postcss` with your preferred package manager:
```sh
- $ npm install -D postcss postcss-prefix-selector
+ $ npm add -D postcss
```
-- Create a file named `docs/.postcssrc.cjs` and add this to it:
+- Create a file named `docs/postcss.config.mjs` and add this to it:
```js
- module.exports = {
- plugins: {
- 'postcss-prefix-selector': {
- prefix: ':not(:where(.vp-raw *))',
- includeFiles: [/vp-doc\.css/],
- transform(prefix, _selector) {
- const [selector, pseudo = ''] = _selector.split(/(:\S*)$/)
- return selector + prefix + pseudo
- }
- }
- }
+ import { postcssIsolateStyles } from 'vitepress'
+
+ export default {
+ plugins: [postcssIsolateStyles()]
}
```
-:::
+ It uses [`postcss-prefix-selector`](https://github.com/postcss/postcss-load-config) under the hood. You can pass its options like this:
+
+ ```js
+ postcssIsolateStyles({
+ includeFiles: [/vp-doc\.css/] // defaults to /base\.css/
+ })
+ ```
## Syntax Highlighting in Code Blocks
@@ -507,6 +523,8 @@ Please see [`markdown` options](../reference/site-config#markdown) for more deta
You can add `:line-numbers` / `:no-line-numbers` mark in your fenced code blocks to override the value set in config.
+You can also customize the starting line number by adding `=` after `:line-numbers`. For example, `:line-numbers=2` means the line numbers in code blocks will start from `2`.
+
**Input**
````md
@@ -521,6 +539,12 @@ const line3 = 'This is line 3'
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```
+
+```ts:line-numbers=2 {1}
+// line-numbers is enabled and start from 2
+const line3 = 'This is line 3'
+const line4 = 'This is line 4'
+```
````
**Output**
@@ -537,6 +561,12 @@ const line2 = 'This is line 2'
const line3 = 'This is line 3'
```
+```ts:line-numbers=2 {1}
+// line-numbers is enabled and start from 2
+const line3 = 'This is line 3'
+const line4 = 'This is line 4'
+```
+
## Import Code Snippets
You can import code snippets from existing files via following syntax:
@@ -563,7 +593,7 @@ It also supports [line highlighting](#line-highlighting-in-code-blocks):
**Output**
-<<< @/snippets/snippet.js{2}
+<<< @/snippets/snippet.js
::: tip
The value of `@` corresponds to the source root. By default it's the VitePress project root, unless `srcDir` is configured. Alternatively, you can also import from relative paths:
@@ -778,19 +808,65 @@ The format of the selected line range can be: `{3,}`, `{,10}`, `{1,10}`
Note that this does not throw errors if your file is not present. Hence, when using this feature make sure that the contents are being rendered as expected.
:::
+## Math Equations
+
+This is currently opt-in. To enable it, you need to install `markdown-it-mathjax3` and set `markdown.math` to `true` in your config file:
+
+```sh
+npm add -D markdown-it-mathjax3
+```
+
+```ts
+// .vitepress/config.ts
+export default {
+ markdown: {
+ math: true
+ }
+}
+```
+
+**Input**
+
+```md
+When $a \ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$ and they are
+$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
+
+**Maxwell's equations:**
+
+| equation | description |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| $\nabla \cdot \vec{\mathbf{B}} = 0$ | divergence of $\vec{\mathbf{B}}$ is zero |
+| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$ | curl of $\vec{\mathbf{E}}$ is proportional to the rate of change of $\vec{\mathbf{B}}$ |
+| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _wha?_ |
+```
+
+**Output**
+
+When $a \ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$ and they are
+$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
+
+**Maxwell's equations:**
+
+| equation | description |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| $\nabla \cdot \vec{\mathbf{B}} = 0$ | divergence of $\vec{\mathbf{B}}$ is zero |
+| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$ | curl of $\vec{\mathbf{E}}$ is proportional to the rate of change of $\vec{\mathbf{B}}$ |
+| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _wha?_ |
+
## Advanced Configuration
VitePress uses [markdown-it](https://github.com/markdown-it/markdown-it) as the Markdown renderer. A lot of the extensions above are implemented via custom plugins. You can further customize the `markdown-it` instance using the `markdown` option in `.vitepress/config.js`:
```js
-const anchor = require('markdown-it-anchor')
+import markdownItAnchor from 'markdown-it-anchor'
+import markdownItFoo from 'markdown-it-foo'
module.exports = {
markdown: {
// options for markdown-it-anchor
// https://github.com/valeriangalliat/markdown-it-anchor#usage
anchor: {
- permalink: anchor.permalink.headerLink()
+ permalink: markdownItAnchor.permalink.headerLink()
},
// options for @mdit-vue/plugin-toc
@@ -799,7 +875,7 @@ module.exports = {
config: (md) => {
// use more markdown-it plugins!
- md.use(require('markdown-it-xxx'))
+ md.use(markdownItFoo)
}
}
}
diff --git a/docs/guide/routing.md b/docs/guide/routing.md
index f5fa9bff..641807e4 100644
--- a/docs/guide/routing.md
+++ b/docs/guide/routing.md
@@ -93,7 +93,33 @@ You can use both absolute and relative paths when linking between pages. Note th
[Getting Started](./getting-started.html)
```
-Learn more about linking to assets such images in [Asset Handling](asset-handling).
+Learn more about linking to assets such images in [Asset Handling](./asset-handling).
+
+### Linking to Non-VitePress Pages
+
+If you want to link to a page in your site that is not generated by VitePress, you'll either need to use the full URL (opens in a new tab) or explicitly specify the target:
+
+**Input**
+
+```md
+[Link to pure.html](/pure.html){target="_self"}
+```
+
+**Output**
+
+[Link to pure.html](/pure.html){target="_self"}
+
+::: tip Note
+
+In Markdown links, the `base` is automatically prepended to the URL. This means that if you want to link to a page outside of your base, you'd need something like `../../pure.html` in the link (resolved relative to the current page by the browser).
+
+Alternatively, you can directly use the anchor tag syntax:
+
+```md
+Link to pure.html
+```
+
+:::
## Generating Clean URL
diff --git a/docs/guide/ssr-compat.md b/docs/guide/ssr-compat.md
index 82eb58e5..dfb0d7c7 100644
--- a/docs/guide/ssr-compat.md
+++ b/docs/guide/ssr-compat.md
@@ -52,6 +52,7 @@ Since [`Theme.enhanceApp`](./custom-theme#theme-interface) can be async, you can
```js
// .vitepress/theme/index.js
+/** @type {import('vitepress').Theme} */
export default {
// ...
async enhanceApp({ app }) {
@@ -63,6 +64,22 @@ export default {
}
```
+If you're using TypeScript:
+```ts
+// .vitepress/theme/index.ts
+import type { Theme } from 'vitepress'
+
+export default {
+ // ...
+ async enhanceApp({ app }) {
+ if (!import.meta.env.SSR) {
+ const plugin = await import('plugin-that-access-window-on-import')
+ app.use(plugin)
+ }
+ }
+} satisfies Theme
+```
+
### `defineClientComponent`
VitePress provides a convenience helper for importing Vue components that access browser APIs on import.
diff --git a/docs/guide/vitepress-init.png b/docs/guide/vitepress-init.png
deleted file mode 100644
index d1805cf7..00000000
Binary files a/docs/guide/vitepress-init.png and /dev/null differ
diff --git a/docs/index.md b/docs/index.md
index b40a9e9b..9bdd428b 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -15,6 +15,9 @@ hero:
- theme: alt
text: View on GitHub
link: https://github.com/vuejs/vitepress
+ image:
+ src: /vitepress-logo-large.webp
+ alt: VitePress
features:
- icon: 📝
@@ -30,3 +33,25 @@ features:
title: Ship Fast Sites
details: Fast initial load with static HTML, fast post-load navigation with client-side routing.
---
+
+
diff --git a/docs/package.json b/docs/package.json
index 35ff39d9..817fb9f6 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -3,11 +3,12 @@
"private": true,
"type": "module",
"scripts": {
- "dev": "vitepress",
+ "dev": "vitepress dev",
"build": "vitepress build",
"preview": "vitepress preview"
},
"devDependencies": {
+ "markdown-it-mathjax3": "^4.3.2",
"vitepress": "workspace:*"
}
}
diff --git a/docs/public/appearance-toggle-transition.webp b/docs/public/appearance-toggle-transition.webp
new file mode 100644
index 00000000..7c2a8d7a
Binary files /dev/null and b/docs/public/appearance-toggle-transition.webp differ
diff --git a/docs/public/vitepress-logo-large.webp b/docs/public/vitepress-logo-large.webp
new file mode 100644
index 00000000..2e47b155
Binary files /dev/null and b/docs/public/vitepress-logo-large.webp differ
diff --git a/docs/public/vitepress-logo-mini.png b/docs/public/vitepress-logo-mini.png
new file mode 100644
index 00000000..db8521e2
Binary files /dev/null and b/docs/public/vitepress-logo-mini.png differ
diff --git a/docs/public/vitepress-logo-mini.svg b/docs/public/vitepress-logo-mini.svg
new file mode 100644
index 00000000..47756f7a
--- /dev/null
+++ b/docs/public/vitepress-logo-mini.svg
@@ -0,0 +1,21 @@
+
diff --git a/docs/public/vitepress-og.jpg b/docs/public/vitepress-og.jpg
new file mode 100644
index 00000000..ea97e47f
Binary files /dev/null and b/docs/public/vitepress-og.jpg differ
diff --git a/docs/reference/default-theme-badge.md b/docs/reference/default-theme-badge.md
index 404d0dd4..e23fde00 100644
--- a/docs/reference/default-theme-badge.md
+++ b/docs/reference/default-theme-badge.md
@@ -32,39 +32,25 @@ Code above renders like:
## Customize Type Color
-You can customize the `background-color` of badges by overriding css variables. The following are the default values:
+You can customize the style of badges by overriding css variables. The following are the default values:
```css
:root {
- --vp-badge-info-border: var(--vp-c-divider-light);
+ --vp-badge-info-border: transparent;
--vp-badge-info-text: var(--vp-c-text-2);
- --vp-badge-info-bg: var(--vp-c-white-soft);
+ --vp-badge-info-bg: var(--vp-c-default-soft);
- --vp-badge-tip-border: var(--vp-c-green-dimm-1);
- --vp-badge-tip-text: var(--vp-c-green-darker);
- --vp-badge-tip-bg: var(--vp-c-green-dimm-3);
+ --vp-badge-tip-border: transparent;
+ --vp-badge-tip-text: var(--vp-c-brand-1);
+ --vp-badge-tip-bg: var(--vp-c-brand-soft);
- --vp-badge-warning-border: var(--vp-c-yellow-dimm-1);
- --vp-badge-warning-text: var(--vp-c-yellow-darker);
- --vp-badge-warning-bg: var(--vp-c-yellow-dimm-3);
+ --vp-badge-warning-border: transparent;
+ --vp-badge-warning-text: var(--vp-c-warning-1);
+ --vp-badge-warning-bg: var(--vp-c-warning-soft);
- --vp-badge-danger-border: var(--vp-c-red-dimm-1);
- --vp-badge-danger-text: var(--vp-c-red-darker);
- --vp-badge-danger-bg: var(--vp-c-red-dimm-3);
-}
-
-.dark {
- --vp-badge-info-border: var(--vp-c-divider-light);
- --vp-badge-info-bg: var(--vp-c-black-mute);
-
- --vp-badge-tip-border: var(--vp-c-green-dimm-2);
- --vp-badge-tip-text: var(--vp-c-green-light);
-
- --vp-badge-warning-border: var(--vp-c-yellow-dimm-2);
- --vp-badge-warning-text: var(--vp-c-yellow-light);
-
- --vp-badge-danger-border: var(--vp-c-red-dimm-2);
- --vp-badge-danger-text: var(--vp-c-red-light);
+ --vp-badge-danger-border: transparent;
+ --vp-badge-danger-text: var(--vp-c-danger-1);
+ --vp-badge-danger-bg: var(--vp-c-danger-soft);
}
```
diff --git a/docs/reference/default-theme-config.md b/docs/reference/default-theme-config.md
index 9b078eae..8402dc08 100644
--- a/docs/reference/default-theme-config.md
+++ b/docs/reference/default-theme-config.md
@@ -66,7 +66,7 @@ export default {
The configuration for the nav menu item. More details in [Default Theme: Nav](./default-theme-nav#navigation-links).
-```js
+```ts
export default {
themeConfig: {
nav: [
@@ -113,7 +113,7 @@ interface NavItemWithChildren {
The configuration for the sidebar menu item. More details in [Default Theme: Sidebar](./default-theme-sidebar).
-```js
+```ts
export default {
themeConfig: {
sidebar: [
@@ -174,26 +174,33 @@ Setting this value to `false` prevents rendering of aside container.\
Setting this value to `true` renders the aside to the right.\
Setting this value to `left` renders the aside to the left.
-## outline
+If you want to disable it for all viewports, you should use `outline: false` instead.
-- Type: `number | [number, number] | 'deep' | false`
-- Default: `2`
-- Can be overridden per page via [frontmatter](./frontmatter-config#outline)
-
-The levels of header to display in the outline. You can specify a particular level by passing a number, or you can provide a level range by passing a tuple containing the bottom and upper limits. When passing `'deep'` which equals `[2, 6]`, all header levels are shown in the outline except `h1`. Set `false` to hide outline.
+## outline
-## outlineTitle
+- Type: `Outline | Outline['level'] | false`
+- Level can be overridden per page via [frontmatter](./frontmatter-config#outline)
-- Type: `string`
-- Default: `On this page`
+Setting this value to `false` prevents rendering of outline container. Refer this interface for more details:
-Can be used to customize the title of the right sidebar (on the top of outline links). This is useful when writing documentation in another language.
+```ts
+interface Outline {
+ /**
+ * The levels of headings to be displayed in the outline.
+ * Single number means only headings of that level will be displayed.
+ * If a tuple is passed, the first number is the minimum level and the second number is the maximum level.
+ * `'deep'` is same as `[2, 6]`, which means all headings from `
` to `
` will be displayed.
+ *
+ * @default 2
+ */
+ level?: number | [number, number] | 'deep'
-```js
-export default {
- themeConfig: {
- outlineTitle: 'In hac pagina'
- }
+ /**
+ * The title to be displayed on the outline.
+ *
+ * @default 'On this page'
+ */
+ label?: string
}
```
@@ -203,7 +210,7 @@ export default {
You may define this option to show your social account links with icons in nav.
-```js
+```ts
export default {
themeConfig: {
socialLinks: [
@@ -275,7 +282,7 @@ export interface Footer {
Edit Link lets you display a link to edit the page on Git management services such as GitHub, or GitLab. See [Default Theme: Edit Link](./default-theme-edit-link) for more details.
-```js
+```ts
export default {
themeConfig: {
editLink: {
@@ -324,7 +331,7 @@ export interface LastUpdatedOptions {
* @default
* { dateStyle: 'short', timeStyle: 'short' }
*/
- formatOptions?: Intl.DateTimeFormatOptions
+ formatOptions?: Intl.DateTimeFormatOptions & { forceLocale?: boolean }
}
```
@@ -374,7 +381,7 @@ Learn more in [Default Theme: Carbon Ads](./default-theme-carbon-ads)
Can be used to customize text appearing above previous and next links. Helpful if not writing docs in English. Also can be used to disable prev/next links globally. If you want to selectively enable/disable prev/next links, you can use [frontmatter](./default-theme-prev-next-links).
-```js
+```ts
export default {
themeConfig: {
docFooter: {
diff --git a/docs/reference/default-theme-home-page.md b/docs/reference/default-theme-home-page.md
index 449602de..bbded876 100644
--- a/docs/reference/default-theme-home-page.md
+++ b/docs/reference/default-theme-home-page.md
@@ -74,7 +74,7 @@ interface HeroAction {
### Customizing the name color
-VitePress uses the brand color (`--vp-c-brand`) for the `name`. However, you may customize this color by overriding `--vp-home-hero-name-color` variable.
+VitePress uses the brand color (`--vp-c-brand-1`) for the `name`. However, you may customize this color by overriding `--vp-home-hero-name-color` variable.
```css
:root {
diff --git a/docs/reference/default-theme-last-updated.md b/docs/reference/default-theme-last-updated.md
index 046214c9..00fed72a 100644
--- a/docs/reference/default-theme-last-updated.md
+++ b/docs/reference/default-theme-last-updated.md
@@ -24,4 +24,4 @@ lastUpdated: false
---
```
-Also refer [Default Theme: Last Updated](./default-theme-last-updated#last-updated) for more details. Any truthy value at theme-level will also enable the feature unless explicitly disabled at site or page level.
+Also refer [Default Theme: Last Updated](./default-theme-config#lastupdated) for more details. Any truthy value at theme-level will also enable the feature unless explicitly disabled at site or page level.
diff --git a/docs/reference/default-theme-layout.md b/docs/reference/default-theme-layout.md
index 27426e9c..246e20fa 100644
--- a/docs/reference/default-theme-layout.md
+++ b/docs/reference/default-theme-layout.md
@@ -36,3 +36,27 @@ Option `home` will generate templated "Homepage". In this layout, you can set ex
## No Layout
If you don't want any layout, you can pass `layout: false` through frontmatter. This option is helpful if you want a fully-customizable landing page (without any sidebar, navbar, or footer by default).
+
+## Custom Layout
+
+You can also use a custom layout:
+
+```md
+---
+layout: foo
+---
+```
+
+This will look for a component named `foo` registered in context. For example, you can register your component globally in `.vitepress/theme/index.ts`:
+
+```ts
+import DefaultTheme from 'vitepress/theme'
+import Foo from './Foo.vue'
+
+export default {
+ extends: DefaultTheme,
+ enhanceApp({ app }) {
+ app.component('foo', Foo)
+ }
+}
+```
diff --git a/docs/reference/default-theme-search.md b/docs/reference/default-theme-search.md
index 2fc852e1..fc516d1d 100644
--- a/docs/reference/default-theme-search.md
+++ b/docs/reference/default-theme-search.md
@@ -98,9 +98,9 @@ export default defineConfig({
Learn more in [MiniSearch docs](https://lucaong.github.io/minisearch/classes/_minisearch_.minisearch.html).
-### Excluding pages from search
+### Custom content renderer
-You can exclude pages from search by adding `search: false` to the frontmatter of the page. Alternatively, you can also pass `exclude` function to `themeConfig.search.options` to exclude pages based on their path relative to `srcDir`:
+You can customize the function used to render the markdown content before indexing it:
```ts
import { defineConfig } from 'vitepress'
@@ -108,8 +108,68 @@ import { defineConfig } from 'vitepress'
export default defineConfig({
themeConfig: {
search: {
+ provider: 'local',
+ options: {
+ /**
+ * @param {string} src
+ * @param {import('vitepress').MarkdownEnv} env
+ * @param {import('markdown-it')} md
+ */
+ _render(src, env, md) {
+ // return html string
+ }
+ }
+ }
+ }
+})
+```
+
+This function will be stripped from client-side site data, so you can use Node.js APIs in it.
+
+#### Example: Excluding pages from search
+
+You can exclude pages from search by adding `search: false` to the frontmatter of the page. Alternatively:
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local',
options: {
- exclude: (path) => path.startsWith('/some/path')
+ _render(src, env, md) {
+ const html = md.render(src, env)
+ if (env.frontmatter?.search === false) return ''
+ if (env.relativePath.startsWith('some/path')) return ''
+ return html
+ }
+ }
+ }
+ }
+})
+```
+
+::: warning Note
+In case a custom `_render` function is provided, you need to handle the `search: false` frontmatter yourself. Also, the `env` object won't be completely populated before `md.render` is called, so any checks on optional `env` properties like `frontmatter` should be done after that.
+:::
+
+#### Example: Transforming content - adding anchors
+
+```ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+ themeConfig: {
+ search: {
+ provider: 'local',
+ options: {
+ _render(src, env, md) {
+ const html = md.render(src, env)
+ if (env.frontmatter?.title)
+ return md.render(`# ${env.frontmatter.title}`) + html
+ return html
+ }
}
}
}
diff --git a/docs/reference/frontmatter-config.md b/docs/reference/frontmatter-config.md
index 10297687..ed4ddf37 100644
--- a/docs/reference/frontmatter-config.md
+++ b/docs/reference/frontmatter-config.md
@@ -159,14 +159,14 @@ aside: false
- Type: `number | [number, number] | 'deep' | false`
- Default: `2`
-The levels of header in the outline to display for the page. It's same as [config.themeConfig.outline](./default-theme-config#outline), and it overrides the theme config.
+The levels of header in the outline to display for the page. It's same as [config.themeConfig.outline.level](./default-theme-config#outline), and it overrides the value set in site-level config.
### lastUpdated
-- Type: `boolean`
+- Type: `boolean | Date`
- Default: `true`
-Whether to display [last updated](./default-theme-last-updated) text in the footer of the current page.
+Whether to display [last updated](./default-theme-last-updated) text in the footer of the current page. If a datetime is specified, it will be displayed instead of the last git modified timestamp.
```yaml
---
diff --git a/docs/reference/site-config.md b/docs/reference/site-config.md
index 73fa8953..18814dd0 100644
--- a/docs/reference/site-config.md
+++ b/docs/reference/site-config.md
@@ -10,7 +10,7 @@ Site config is where you can define the global settings of the site. App config
### Config Resolution
-The config file is always resolved from `/.vitepress/config.[ext]`, where `` is your VitePress [project root](../guide/routing#root-and-source-directory), and `[ext]` is one of the supported file extensions. TypeScript is supported out of the box. Supported extensions include `.js`, `.ts`, `.cjs`, `.mjs`, `.cts`, and `.mts`.
+The config file is always resolved from `/.vitepress/config.[ext]`, where `` is your VitePress [project root](../guide/routing#root-and-source-directory), and `[ext]` is one of the supported file extensions. TypeScript is supported out of the box. Supported extensions include `.js`, `.ts`, `.mjs`, and `.mts`.
It is recommended to use ES modules syntax in config files. The config file should default export an object:
@@ -155,17 +155,56 @@ export default {
Additional elements to render in the `` tag in the page HTML. The user-added tags are rendered before the closing `head` tag, after VitePress tags.
+```ts
+type HeadConfig =
+ | [string, Record]
+ | [string, Record, string]
+```
+
+#### Example: Adding a favicon
+
+```ts
+export default {
+ head: [['link', { rel: 'icon', href: '/favicon.ico' }]]
+} // put favicon.ico in public directory, if base is set, use /base/favicon.ico
+
+/* Would render:
+
+*/
+```
+
+#### Example: Adding Google Fonts
+
```ts
export default {
head: [
+ [
+ 'link',
+ { rel: 'preconnect', href: 'https://fonts.googleapis.com' }
+ ],
[
'link',
{ rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }
- // would render:
- //
- //
],
+ [
+ 'link',
+ { href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap', rel: 'stylesheet' }
+ ]
+ ]
+}
+
+/* Would render:
+
+
+
+*/
+```
+#### Example: Registering a service worker
+
+```ts
+export default {
+ head: [
[
'script',
{ id: 'register-sw' },
@@ -174,24 +213,50 @@ export default {
navigator.serviceWorker.register('/sw.js')
}
})()`
- // would render:
- //
- //
]
]
}
+
+/* Would render:
+
+*/
```
+#### Example: Using Google Analytics
+
```ts
-type HeadConfig =
- | [string, Record]
- | [string, Record, string]
+export default {
+ head: [
+ [
+ 'script',
+ { async: '', src: 'https://www.googletagmanager.com/gtag/js?id=TAG_ID' }
+ ],
+ [
+ 'script',
+ {},
+ `window.dataLayer = window.dataLayer || [];
+ function gtag(){dataLayer.push(arguments);}
+ gtag('js', new Date());
+ gtag('config', 'TAG_ID');`
+ ]
+ ]
+}
+
+/* Would render:
+
+
+*/
```
### lang
@@ -239,7 +304,7 @@ Enabling this may require additional configuration on your hosting platform. For
- Type: `Record`
-Defines custom directory <-> URL mappings. See [Routing: Route Rewrites](../guide/routing#route-rewrites) for more details.
+Defines custom directory <-> URL mappings. See [Routing: Route Rewrites](../guide/routing#route-rewrites) for more details.
```ts
export default {
@@ -361,7 +426,7 @@ When set to `true`, the production app will be built in [MPA Mode](../guide/mpa-
### appearance
-- Type: `boolean | 'dark'`
+- Type: `boolean | 'dark' | 'force-dark' | import('@vueuse/core').UseDarkOptions`
- Default: `true`
Whether to enable dark mode (by adding the `.dark` class to the `` element).
@@ -372,6 +437,8 @@ Whether to enable dark mode (by adding the `.dark` class to the `` element
This option injects an inline script that restores users settings from local storage using the `vitepress-theme-appearance` key. This ensures the `.dark` class is applied before the page is rendered to avoid flickering.
+`appearance.initialValue` can only be `'dark' | undefined`. Refs or getters are not supported.
+
### lastUpdated
- Type: `boolean`
@@ -391,18 +458,7 @@ Configure Markdown parser options. VitePress uses [Markdown-it](https://github.c
```js
export default {
- markdown: {
- theme: 'material-theme-palenight',
- lineNumbers: true,
-
- // adjust how header anchors are generated,
- // useful for integrating with tools that use different conventions
- anchor: {
- slugify(str) {
- return encodeURIComponent(str)
- }
- }
- }
+ markdown: {...}
}
```
@@ -458,8 +514,33 @@ interface MarkdownOptions extends MarkdownIt.Options {
// See: https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
toc?: TocPluginOptions
+ // @mdit-vue/plugin-component plugin options.
+ // See: https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-component#options
+ component?: ComponentPluginOptions
+
// Configure the Markdown-it instance.
config?: (md: MarkdownIt) => void
+
+ // Same as `config` but will be applied before all other plugins.
+ preConfig?: (md: MarkdownIt) => void
+
+ // Disable cache (experimental)
+ cache?: boolean
+
+ // Math support (experimental)
+ // You need to install `markdown-it-mathjax3` and set `math` to `true` to enable it.
+ // You can also pass options to `markdown-it-mathjax3` here.
+ // See: https://github.com/tani/markdown-it-mathjax3#customization
+ math?: any
+
+ // Global custom container titles
+ container?: {
+ infoLabel?: string
+ tipLabel?: string
+ warningLabel?: string
+ dangerLabel?: string
+ detailsLabel?: string
+ }
}
```
@@ -543,7 +624,7 @@ interface SSGContext {
`transformHead` is a build hook to transform the head before generating each page. It will allow you to add head entries that cannot be statically added to your VitePress config. You only need to return extra entries, they will be merged automatically with the existing ones.
::: warning
-Don't mutate anything inside the `ctx`.
+Don't mutate anything inside the `context`.
:::
```ts
@@ -568,14 +649,34 @@ interface TransformContext {
}
```
+Note that this hook is only called when generating the site statically. It is not called during dev. If you need to add dynamic head entries during dev, you can use the [`transformPageData`](#transformpagedata) hook instead:
+
+```ts
+export default {
+ transformPageData(pageData) {
+ pageData.frontmatter.head ??= []
+ pageData.frontmatter.head.push([
+ 'meta',
+ {
+ name: 'og:title',
+ content:
+ pageData.frontmatter.layout === 'home'
+ ? `VitePress`
+ : `${pageData.title} | VitePress`
+ }
+ ])
+ }
+}
+```
+
### transformHtml
-- Type: `(code: string, id: string, ctx: TransformContext) => Awaitable`
+- Type: `(code: string, id: string, context: TransformContext) => Awaitable`
`transformHtml` is a build hook to transform the content of each page before saving to disk.
::: warning
-Don't mutate anything inside the `ctx`. Also, modifying the html content may cause hydration problems in runtime.
+Don't mutate anything inside the `context`. Also, modifying the html content may cause hydration problems in runtime.
:::
```ts
@@ -588,12 +689,12 @@ export default {
### transformPageData
-- Type: `(pageData: PageData, ctx: TransformPageContext) => Awaitable | { [key: string]: any } | void>`
+- Type: `(pageData: PageData, context: TransformPageContext) => Awaitable | { [key: string]: any } | void>`
-`transformPageData` is a hook to transform the `pageData` of each page. You can directly mutate `pageData` or return changed values which will be merged into PageData.
+`transformPageData` is a hook to transform the `pageData` of each page. You can directly mutate `pageData` or return changed values which will be merged into the page data.
::: warning
-Don't mutate anything inside the `ctx`.
+Don't mutate anything inside the `context` and be careful that this might impact the performance of dev server, especially if you have some network requests or heavy computations (like generating images) in the hook. You can check for `process.env.NODE_ENV === 'production'` for conditional logic.
:::
```ts
diff --git a/docs/snippets/init.ansi b/docs/snippets/init.ansi
new file mode 100644
index 00000000..287149f9
--- /dev/null
+++ b/docs/snippets/init.ansi
@@ -0,0 +1,16 @@
+[0;90m┌[0m [0;36;1mWelcome to VitePress{target="\_self"}
-[链接到 pure.html](/pure.html){target="\_blank"}
+[链接到 pure.html](/pure.html){target="\_blank"} -->
## 根 URL {#base-url}
diff --git a/docs/zh/guide/data-loading.md b/docs/zh/guide/data-loading.md
index 22cf48a9..56a318ea 100644
--- a/docs/zh/guide/data-loading.md
+++ b/docs/zh/guide/data-loading.md
@@ -13,7 +13,7 @@ VitePress 提供了一个叫做**数据加载器**的功能，它允许你加载
export default {
load() {
return {
- data: 'hello',
+ hello: 'world',
}
},
}
@@ -35,7 +35,7 @@ import { data } from './example.data.js'
```json
{
- "data": "hello"
+ "hello": "world"
}
```
@@ -99,7 +99,8 @@ export default createContentLoader('posts/*.md' /* options */)
```ts
interface ContentData {
- // mapped absolute URL for the page. e.g. /posts/hello.html
+ // mapped URL for the page. e.g. /posts/hello.html (does not include base)
+ // manually iterate or use custom `transform` to normalize the paths
url: string
// frontmatter data of the page
frontmatter: Record
diff --git a/docs/zh/guide/deploy.md b/docs/zh/guide/deploy.md
index 4675934f..95799318 100644
--- a/docs/zh/guide/deploy.md
+++ b/docs/zh/guide/deploy.md
@@ -111,7 +111,7 @@ Cache-Control: max-age=31536000,immutable
- **构建命令：** `npm run docs:build`
- **输出目录：** `docs/.vitepress/dist`
-- **node 版本：** `16` (或更高版本，默认情况下通常为 14 或 16，但在 Cloudflare 页面上，默认值仍然是 12，因此你可能需要[更改该版本](https://developers.cloudflare.com/pages/platform/build-configuration/))
+- **node 版本：** `18` (或更高版本)
::: warning 警告
不要为 HTML 代码启用 _Auto Minify_ 等选项。它将从输出中删除对 Vue 有意义的注释。如果被删除，你可能会看到 [hydration(HTML 添加交互的过程)](https://blog.csdn.net/qq_41800366/article/details/117738916) mismatch 错误。
@@ -148,30 +148,33 @@ concurrency:
cancel-in-progress: false
jobs:
- # Build job
- build:
- runs-on: ubuntu-latest
- steps:
- - name: Checkout
- uses: actions/checkout@v3
- with:
- fetch-depth: 0 # Not needed if lastUpdated is not enabled
- # - uses: pnpm/action-setup@v2 # Uncomment this if you're using pnpm
- - name: Setup Node
- uses: actions/setup-node@v3
- with:
- node-version: 18
- cache: npm # or pnpm / yarn
- - name: Setup Pages
- uses: actions/configure-pages@v3
- - name: Install dependencies
- run: npm ci # or pnpm install / yarn install
- - name: Build with VitePress
- run: npm run docs:build # or pnpm docs:build / yarn docs:build
- - name: Upload artifact
- uses: actions/upload-pages-artifact@v2
- with:
- path: docs/.vitepress/dist
+ # Build job
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v3
+ with:
+ fetch-depth: 0 # Not needed if lastUpdated is not enabled
+ # - uses: pnpm/action-setup@v2 # Uncomment this if you're using pnpm
+ # - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun
+ - name: Setup Node
+ uses: actions/setup-node@v3
+ with:
+ node-version: 18
+ cache: npm # or pnpm / yarn
+ - name: Setup Pages
+ uses: actions/configure-pages@v3
+ - name: Install dependencies
+ run: npm ci # or pnpm install / yarn install / bun install
+ - name: Build with VitePress
+ run: |
+ npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build
+ touch docs/.vitepress/dist/.nojekyll
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v2
+ with:
+ path: docs/.vitepress/dist
# Deployment job
deploy:
@@ -202,7 +205,7 @@ jobs:
2. 在项目的根目录中创建一个名为 `.gitlab-ci.yml` 的文件，其中包含以下内容。每当您更改内容时，都会自动构建和部署您的网站：
```yaml
- image: node:16
+ image: node:18
pages:
cache:
paths:
diff --git a/docs/zh/guide/extending-default-theme.md b/docs/zh/guide/extending-default-theme.md
index b89f12c6..8781d597 100644
--- a/docs/zh/guide/extending-default-theme.md
+++ b/docs/zh/guide/extending-default-theme.md
@@ -1,3 +1,7 @@
+---
+outline: deep
+---
+
# 扩展默认主题 {#extending-the-default-theme}
VitePress 默认的主题已经针对文档进行了优化，并且可以进行定制。请参考 [默认主题配置概览](../reference/default-theme-config) 获取完整的选项列表。
@@ -29,8 +33,8 @@ export default DefaultTheme
```css
/* .vitepress/theme/custom.css */
:root {
- --vp-c-brand: #646cff;
- --vp-c-brand-light: #747bff;
+ --vp-c-brand-1: #646cff;
+ --vp-c-brand-2: #747bff;
}
```
@@ -67,24 +71,24 @@ export default DefaultTheme
```js
// .vitepress/config.js
export default {
- transformHead({ assets }) {
- // adjust the regex accordingly to match your font
- const myFontFile = assets.find(file => /font-name\.\w+\.woff2/)
- if (myFontFile) {
- return [
- [
- 'link',
- {
- rel: 'preload',
- href: myFontFile,
- as: 'font',
- type: 'font/woff2',
- crossorigin: ''
- }
- ]
- ]
- }
- }
+ transformHead({ assets }) {
+ // adjust the regex accordingly to match your font
+ const myFontFile = assets.find((file) => /font-name\.\w+\.woff2/)
+ if (myFontFile) {
+ return [
+ [
+ 'link',
+ {
+ rel: 'preload',
+ href: myFontFile,
+ as: 'font',
+ type: 'font/woff2',
+ crossorigin: '',
+ },
+ ],
+ ]
+ }
+ },
}
```
@@ -94,15 +98,32 @@ export default {
// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
+/** @type {import('vitepress').Theme} */
export default {
- extends: DefaultTheme,
- enhanceApp(ctx) {
- // register your custom global components
- ctx.app.component('MyGlobalComponent' /* ... */)
- }
+ extends: DefaultTheme,
+ enhanceApp(ctx) {
+ // register your custom global components
+ ctx.app.component('MyGlobalComponent' /* ... */)
+ },
}
```
+如果你使用 TypeScript:
+
+```ts
+// .vitepress/theme/index.ts
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+
+export default {
+ extends: DefaultTheme,
+ async enhanceApp({ app }) {
+ // register your custom global components
+ ctx.app.component('MyGlobalComponent' /* ... */)
+ },
+} satisfies Theme
+```
+
因为我们使用 Vite，你还可以利用 Vite 的 [glob 导入功能](https://cn.vitejs.dev/guide/features.html#glob-import)来自动注册一个组件目录。
## 布局插槽 {#layout-slots}
@@ -115,10 +136,10 @@ import DefaultTheme from 'vitepress/theme'
import MyLayout from './MyLayout.vue'
export default {
- ...DefaultTheme,
- // override the Layout with a wrapper component that
- // injects the slots
- Layout: MyLayout
+ ...DefaultTheme,
+ // override the Layout with a wrapper component that
+ // injects the slots
+ Layout: MyLayout,
}
```
@@ -131,11 +152,9 @@ const { Layout } = DefaultTheme
-
-
- My custom sidebar top content
-
-
+
+ My custom sidebar top content
+
```
@@ -148,12 +167,12 @@ import DefaultTheme from 'vitepress/theme'
import MyComponent from './MyComponent.vue'
export default {
- ...DefaultTheme,
- Layout() {
- return h(DefaultTheme.Layout, null, {
- 'aside-outline-before': () => h(MyComponent)
- })
- }
+ ...DefaultTheme,
+ Layout() {
+ return h(DefaultTheme.Layout, null, {
+ 'aside-outline-before': () => h(MyComponent),
+ })
+ },
}
```
@@ -199,18 +218,16 @@ import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vitepress'
export default defineConfig({
- vite: {
- resolve: {
- alias: [
- {
- find: /^.*\/VPNavBar\.vue$/,
- replacement: fileURLToPath(
- new URL('./components/CustomNavBar.vue', import.meta.url)
- )
- }
- ]
- }
- }
+ vite: {
+ resolve: {
+ alias: [
+ {
+ find: /^.*\/VPNavBar\.vue$/,
+ replacement: fileURLToPath(new URL('./components/CustomNavBar.vue', import.meta.url)),
+ },
+ ],
+ },
+ },
})
```
diff --git a/docs/zh/guide/getting-started.md b/docs/zh/guide/getting-started.md
index 3cdedb58..afc66012 100644
--- a/docs/zh/guide/getting-started.md
+++ b/docs/zh/guide/getting-started.md
@@ -8,7 +8,7 @@
### 前置知识 {#prerequisites}
-- [Node.js](https://nodejs.org/) 16 及以上版本。
+- [Node.js](https://nodejs.org/) 18 及以上版本。
- 通过命令行界面 (CLI) 访问 VitePress 的终端。
- 支持 [Markdown](https://en.wikipedia.org/wiki/Markdown) 语法的编辑器。
- 推荐 [VSCode](https://code.visualstudio.com/) 及其[官方 Vue 扩展](https://marketplace.visualstudio.com/items?itemName=Vue.volar)。
@@ -18,17 +18,21 @@ VitePress 可以单独使用，也可以安装到现有项目中。在这两种
::: code-group
```sh [npm]
-$ npm install -D vitepress
+$ npm add -D vitepress
```
```sh [pnpm]
-$ pnpm add -D vitepress@latest
+$ pnpm add -D vitepress
```
```sh [yarn]
$ yarn add -D vitepress
```
+```sh [bun]
+$ bun add -D vitepress
+```
+
:::
::: details 遇到了 missing peer deps 警告？
@@ -47,6 +51,11 @@ $ yarn add -D vitepress
:::
+::: tip 注意
+VitePress 是仅 ESM 的软件包。不要使用 `require()` 导入它，并确保最新的 `package.json` 包含 `"type": "module"`，或者更改相关文件的文件扩展名，例如`.vitepress/config.js` 到 `.mjs`/`.mts`。更多详情请参考[Vite 故障排除指南](http://vitejs.dev/guide/troubleshooting.html#this-package-is-esm-only)。此外，在异步 CJS 上下文中，您可以使用 `await import('vitepress')` 代替。
+
+:::
+
### 安装向导 {#setup-wizard}
VitePress 附带一个命令行设置向导，可以帮助你构建一个基本项目。安装后，通过运行以下命令启动向导：
@@ -65,9 +74,7 @@ $ pnpm dlx vitepress init
你将需要回答几个简单的问题：
-
-