msb-public
/
vitepress
mirror of https://github.com/vuejs/vitepress
2
1
Code Issues Projects Releases Wiki Activity

Merge 3f7242bb2c into c61182ab27

Browse Source
pull/4060/merge
Polaris 9 months ago committed by GitHub
parent c61182ab27 3f7242bb2c
commit 7ac2819824
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
25 changed files with 133 additions and 133 deletions
Show Stats Download Patch File Download Diff File

10
docs/en/guide/asset-handling.md
Unescape View File

@ -8,9 +8,9 @@ All Markdown files are compiled into Vue components and processed by [Vite](http
![An image](./image.png) ![An image](./image.png)
``` ```
You can reference static assets in your markdown files, your `*.vue` components in the theme, styles and plain `.css` files either using absolute public paths (based on project root) or relative paths (based on your file system). The latter is similar to the behavior you are used to if you have used Vite, Vue CLI, or webpack's `file-loader`. You can reference static assets in your markdown files, your `*.vue` components in the theme, styles, and plain `.css` files either using absolute public paths (based on project root) or relative paths (based on your file system). The latter is similar to the behavior you are used to if you have used Vite, Vue CLI, or webpack's `file-loader`.
Common image, media, and font filetypes are detected and included as assets automatically. Common image, media, and font file types are detected and included as assets automatically.
::: tip Linked files are not treated as assets ::: tip Linked files are not treated as assets
PDFs or other documents referenced by links within markdown files are not automatically treated as assets. To make linked files accessible, you must manually place them within the [`public`](#the-public-directory) directory of your project. PDFs or other documents referenced by links within markdown files are not automatically treated as assets. To make linked files accessible, you must manually place them within the [`public`](#the-public-directory) directory of your project.
@ -24,11 +24,11 @@ All **static** path references, including absolute paths, should be based on you
Sometimes you may need to provide static assets that are not directly referenced in any of your Markdown or theme components, or you may want to serve certain files with the original filename. Examples of such files include `robots.txt`, favicons, and PWA icons. Sometimes you may need to provide static assets that are not directly referenced in any of your Markdown or theme components, or you may want to serve certain files with the original filename. Examples of such files include `robots.txt`, favicons, and PWA icons.
You can place these files in the `public` directory under the [source directory](./routing#source-directory). For example, if your project root is `./docs` and using default source directory location, then your public directory will be `./docs/public`. You can place these files in the `public` directory under the [source directory](./routing#source-directory). For example, if your project root is `./docs` and using the default source directory location, then your public directory will be `./docs/public`.
Assets placed in `public` will be copied to the root of the output directory as-is. Assets placed in `public` will be copied to the root of the output directory as-is.
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`. Note that you should reference files placed in `public` using the root absolute path - for example, `public/icon.png` should always be referenced in source code as `/icon.png`.
## Base URL ## Base URL
@ -48,7 +48,7 @@ However, if you are authoring a theme component that links to assets dynamically
<img :src="theme.logoPath" /> <img :src="theme.logoPath" />
``` ```
In this case it is recommended to wrap the path with the [`withBase` helper](../reference/runtime-api#withbase) provided by VitePress: In this case, it is recommended to wrap the path with the [`withBase` helper](../reference/runtime-api#withbase) provided by VitePress:
```vue ```vue
<script setup> <script setup>

4
docs/en/guide/cms.md
Unescape View File

@ -10,7 +10,7 @@ Connecting VitePress to a CMS will largely revolve around [Dynamic Routes](./rou
Since each CMS will work differently, here we can only provide a generic workflow that you will need to adapt to your specific scenario. Since each CMS will work differently, here we can only provide a generic workflow that you will need to adapt to your specific scenario.
1. If your CMS requires authentication, create an `.env` file to store your API tokens and load it so: 1. If your CMS requires authentication, create a `.env` file to store your API tokens and load it so:
```js ```js
// posts/[id].paths.js // posts/[id].paths.js
@ -41,7 +41,7 @@ Since each CMS will work differently, here we can only provide a generic workflo
} }
``` ```
3. Render the content in the page: 3. Render the content on the page:
```md ```md
# {{ $params.title }} # {{ $params.title }}

8
docs/en/guide/custom-theme.md
Unescape View File

@ -15,7 +15,7 @@ You can enable a custom theme by creating a `.vitepress/theme/index.js` or `.vit
└─ package.json └─ package.json
``` ```
VitePress will always use the custom theme instead of the default theme when it detects presence of a theme entry file. You can, however, [extend the default theme](./extending-default-theme) to perform advanced customizations on top of it. VitePress will always use the custom theme instead of the default theme when it detects the presence of a theme entry file. You can, however, [extend the default theme](./extending-default-theme) to perform advanced customizations on top of it.
## Theme Interface ## Theme Interface
@ -100,7 +100,7 @@ const { page } = useData()
</template> </template>
``` ```
The [`useData()`](../reference/runtime-api#usedata) helper provides us with all the runtime data we need to conditionally render different layouts. One of the other data we can access is the current page's frontmatter. We can leverage this to allow the end user to control the layout in each page. For example, the user can indicate the page should use a special home page layout with: The [`useData()`](../reference/runtime-api#usedata) helper provides us with all the runtime data we need to conditionally render different layouts. One of the other data we can access is the current page's frontmatter. We can leverage this to allow the end user to control the layout of each page. For example, the user can indicate the page should use a special home page layout with:
```md ```md
--- ---
@ -150,7 +150,7 @@ const { page, frontmatter } = useData()
</template> </template>
``` ```
Consult the [Runtime API Reference](../reference/runtime-api) for everything available in theme components. In addition, you can leverage [Build-Time Data Loading](./data-loading) to generate data-driven layout - for example, a page that lists all blog posts in the current project. Consult the [Runtime API Reference](../reference/runtime-api) for everything available in theme components. In addition, you can leverage [Build-Time Data Loading](./data-loading) to generate a data-driven layout - for example, a page that lists all blog posts in the current project.
## Distributing a Custom Theme ## Distributing a Custom Theme
@ -193,7 +193,7 @@ export default {
} }
``` ```
If the theme requires special VitePress config, you will need to also extend it in your own config: If the theme requires a special VitePress config, you will need to also extend it in your own config:
```ts ```ts
// .vitepress/config.ts // .vitepress/config.ts

8
docs/en/guide/data-loading.md
Unescape View File

@ -2,7 +2,7 @@
VitePress provides a feature called **data loaders** that allows you to load arbitrary data and import it from pages or components. The data loading is executed **only at build time**: the resulting data will be serialized as JSON in the final JavaScript bundle. VitePress provides a feature called **data loaders** that allows you to load arbitrary data and import it from pages or components. The data loading is executed **only at build time**: the resulting data will be serialized as JSON in the final JavaScript bundle.
Data loaders can be used to fetch remote data, or generate metadata based on local files. For example, you can use data loaders to parse all your local API pages and automatically generate an index of all API entries. Data loaders can be used to fetch remote data to or generate metadata based on local files. For example, you can use data loaders to parse all your local API pages and automatically generate an index of all API entries.
## Basic Usage ## Basic Usage
@ -82,7 +82,7 @@ export default {
## `createContentLoader` ## `createContentLoader`
When building a content focused site, we often need to create an "archive" or "index" page: a page where we list all available entries in our content collection, for example blog posts or API pages. We **can** implement this directly with the data loader API, but since this is such a common use case, VitePress also provides a `createContentLoader` helper to simplify this: When building a content-focused site, we often need to create an "archive" or "index" page: a page where we list all available entries in our content collection, for example, blog posts or API pages. We **can** implement this directly with the data loader API, but since this is such a common use case, VitePress also provides a `createContentLoader` helper to simplify this:
```js ```js
// posts.data.js // posts.data.js
@ -91,7 +91,7 @@ import { createContentLoader } from 'vitepress'
export default createContentLoader('posts/*.md', /* options */) export default createContentLoader('posts/*.md', /* options */)
``` ```
The helper takes a glob pattern relative to the [source directory](./routing#source-directory), and returns a `{ watch, load }` data loader object that can be used as the default export in a data loader file. It also implements caching based on file modified timestamps to improve dev performance. The helper takes a glob pattern relative to the [source directory](./routing#source-directory), and returns a `{ watch, load }` data loader object that can be used as the default export in a data loader file. It also implements caching based on file modification timestamps to improve dev performance.
Note the loader only works with Markdown files - matched non-Markdown files will be skipped. Note the loader only works with Markdown files - matched non-Markdown files will be skipped.
@ -113,7 +113,7 @@ interface ContentData {
} }
``` ```
By default, only `url` and `frontmatter` are provided. This is because the loaded data will be inlined as JSON in the client bundle, so we need to be cautious about its size. Here's an example using the data to build a minimal blog index page: By default, only `url` and `frontmatter` are provided. This is because the loaded data will be inlined as JSON in the client bundle, so we need to be cautious about its size. Here's an example which uses the data to build a minimal blog index page:
```vue ```vue
<script setup> <script setup>

12
docs/en/guide/deploy.md
Unescape View File

@ -57,7 +57,7 @@ By default, we assume the site is going to be deployed at the root path of a dom
If you have control over the HTTP headers on your production server, you can configure `cache-control` headers to achieve better performance on repeated visits. If you have control over the HTTP headers on your production server, you can configure `cache-control` headers to achieve better performance on repeated visits.
The production build uses hashed file names for static assets (JavaScript, CSS and other imported assets not in `public`). If you inspect the production preview using your browser devtools' network tab, you will see files like `app.4f283b18.js`. The production build uses hashed file names for static assets (JavaScript, CSS, and other imported assets not in `public`). If you inspect the production preview using your browser developer tools' network tab, you will see files like `app.4f283b18.js`.
This `4f283b18` hash is generated from the content of this file. The same hashed URL is guaranteed to serve the same file content - if the contents change, the URLs change too. This means you can safely use the strongest cache headers for these files. All such files will be placed under `assets/` in the output directory, so you can configure the following header for them: This `4f283b18` hash is generated from the content of this file. The same hashed URL is guaranteed to serve the same file content - if the contents change, the URLs change too. This means you can safely use the strongest cache headers for these files. All such files will be placed under `assets/` in the output directory, so you can configure the following header for them:
@ -114,7 +114,7 @@ Set up a new project and change these settings using your dashboard:
- **Node Version:** `18` (or above) - **Node Version:** `18` (or above)
::: warning ::: 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. Don't enable options like _Auto Minify_ for HTML code. It will remove comments, which have meaning to Vue, from output. You may see hydration mismatch errors if they get removed.
::: :::
### GitHub Pages ### GitHub Pages
@ -200,7 +200,7 @@ Don't enable options like _Auto Minify_ for HTML code. It will remove comments f
### GitLab Pages ### GitLab Pages
1. Set `outDir` in VitePress config to `../public`. Configure `base` option to `'/<repository>/'` if you want to deploy to `https://<username>.gitlab.io/<repository>/`. You don't need `base` if you're deploying to custom domain, user or group pages, or have "Use unique domain" setting enabled in GitLab. 1. Set `outDir` in VitePress config to `../public`. Configure `base` option to `'/<repository>/'` if you want to deploy to `https://<username>.gitlab.io/<repository>/`. You don't need `base` if you're deploying to a custom domain, user/group pages, or have the "Use unique domain" setting enabled in GitLab.
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: 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:
@ -272,7 +272,7 @@ Don't enable options like _Auto Minify_ for HTML code. It will remove comments f
### Heroku ### Heroku
1. Follow documentation and guide given in [`heroku-buildpack-static`](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-static). 1. Follow the documentation and guide avaliable at [`heroku-buildpack-static`](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-static).
2. Create a file called `static.json` in the root of your project with the below content: 2. Create a file called `static.json` in the root of your project with the below content:
@ -284,7 +284,7 @@ Don't enable options like _Auto Minify_ for HTML code. It will remove comments f
### Edgio ### Edgio
Refer [Creating and Deploying a VitePress App To Edgio](https://docs.edg.io/guides/vitepress). Refer to [Creating and Deploying a VitePress App To Edgio](https://docs.edg.io/guides/vitepress).
### Kinsta Static Site Hosting ### Kinsta Static Site Hosting
@ -296,7 +296,7 @@ You can deploy your VitePress project to [Stormkit](https://www.stormkit.io) by
### Nginx ### Nginx
Here is a example of an Nginx server block configuration. This setup includes gzip compression for common text-based assets, rules for serving your VitePress site's static files with proper caching headers as well as handling `cleanUrls: true`. Here is an example of an Nginx server block configuration. This setup includes gzip compression for common text-based assets, rules for serving your VitePress site's static files with proper caching headers, as well as handling `cleanUrls: true`.
```nginx ```nginx
server { server {

18
docs/en/guide/extending-default-theme.md
Unescape View File

@ -4,12 +4,12 @@ outline: deep
# Extending the Default Theme # 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. 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.
However, there are a number of cases where configuration alone won't be enough. For example: However, there are a number of cases where configuration alone won't be enough. For example:
1. You need to tweak the CSS styling; 1. You need to tweak the CSS styling;
2. You need to modify the Vue app instance, for example to register global components; 2. You need to modify the Vue app instance, for example, to register global components;
3. You need to inject custom content into the theme via layout slots. 3. You need to inject custom content into the theme via layout slots.
These advanced customizations will require using a custom theme that "extends" the default theme. These advanced customizations will require using a custom theme that "extends" the default theme.
@ -20,7 +20,7 @@ Before proceeding, make sure to first read [Using a Custom Theme](./custom-theme
## Customizing CSS ## Customizing CSS
The default theme CSS is customizable by overriding root level CSS variables: The default theme CSS is customizable by overriding root-level CSS variables:
```js ```js
// .vitepress/theme/index.js // .vitepress/theme/index.js
@ -42,7 +42,7 @@ See [default theme CSS variables](https://github.com/vuejs/vitepress/blob/main/s
## Using Different Fonts ## Using Different Fonts
VitePress uses [Inter](https://rsms.me/inter/) as the default font, and will include the fonts in the build output. The font is also auto preloaded in production. However, this may not be desirable if you want to use a different main font. VitePress uses [Inter](https://rsms.me/inter/) as the default font, and will include the fonts in the build output. The font is also automatically preloaded in production. However, this may not be desirable if you want to use a different main font.
To avoid including Inter in the build output, import the theme from `vitepress/theme-without-fonts` instead: To avoid including Inter in the build output, import the theme from `vitepress/theme-without-fonts` instead:
@ -66,7 +66,7 @@ export default DefaultTheme
If you are using optional components like the [Team Page](../reference/default-theme-team-page) components, make sure to also import them from `vitepress/theme-without-fonts`! If you are using optional components like the [Team Page](../reference/default-theme-team-page) components, make sure to also import them from `vitepress/theme-without-fonts`!
::: :::
If your font is a local file referenced via `@font-face`, it will be processed as an asset and included under `.vitepress/dist/assets` with hashed filename. To preload this file, use the [transformHead](../reference/site-config#transformhead) build hook: If your font is a local file referenced via `@font-face`, it will be processed as an asset and included under `.vitepress/dist/assets` with a hashed filename. To preload this file, use the [transformHead](../reference/site-config#transformhead) build hook:
```js ```js
// .vitepress/config.js // .vitepress/config.js
@ -123,7 +123,7 @@ export default {
} satisfies Theme } 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. 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 ## Layout Slots
@ -159,7 +159,7 @@ const { Layout } = DefaultTheme
</template> </template>
``` ```
Or you could use render function as well. Or you could use a render function as well.
```js ```js
// .vitepress/theme/index.js // .vitepress/theme/index.js
@ -308,7 +308,7 @@ Result (**warning!**: flashing colors, sudden movements, bright lights):
</details> </details>
Refer [Chrome Docs](https://developer.chrome.com/docs/web-platform/view-transitions/) from more details on view transitions. Refer [Chrome Docs](https://developer.chrome.com/docs/web-platform/view-transitions/) for more details on view transitions.
### On Route Change ### On Route Change
@ -338,4 +338,4 @@ export default defineConfig({
}) })
``` ```
To know the exact name of the component refer [our source code](https://github.com/vuejs/vitepress/tree/main/src/client/theme-default/components). Since the components are internal, there is a slight chance their name is updated between minor releases. To know the exact name of the component, please refer to [our source code](https://github.com/vuejs/vitepress/tree/main/src/client/theme-default/components). Since these components are internal, there is a slight chance their names may be updated between minor releases.

4
docs/en/guide/frontmatter.md
Unescape View File

@ -2,7 +2,7 @@
## Usage ## Usage
VitePress supports YAML frontmatter in all Markdown files, parsing them with [gray-matter](https://github.com/jonschlinkert/gray-matter). The frontmatter must be at the top of the Markdown file (before any elements including `<script>` tags), and must take the form of valid YAML set between triple-dashed lines. Example: VitePress supports YAML frontmatter in all Markdown files, parsing them with [gray-matter](https://github.com/jonschlinkert/gray-matter). The frontmatter must be at the top of the Markdown file (before any elements including `<script>` tags) and must take the form of valid YAML set between triple-dashed lines. Example:
```md ```md
--- ---
@ -32,7 +32,7 @@ editLink: true
Guide content Guide content
``` ```
You can also access current page's frontmatter data in `<script setup>` with the [`useData()`](../reference/runtime-api#usedata) helper. You can also access the current page's frontmatter data in `<script setup>` with the [`useData()`](../reference/runtime-api#usedata) helper.
## Alternative Frontmatter Formats ## Alternative Frontmatter Formats

4
docs/en/guide/i18n.md
Unescape View File

@ -51,7 +51,7 @@ interface LocaleSpecificConfig<ThemeConfig = any> {
Refer [`DefaultTheme.Config`](https://github.com/vuejs/vitepress/blob/main/types/default-theme.d.ts) interface for details on customizing the placeholder texts of the default theme. Don't override `themeConfig.algolia` or `themeConfig.carbonAds` at locale-level. Refer [Algolia docs](../reference/default-theme-search#i18n) for using multilingual search. Refer [`DefaultTheme.Config`](https://github.com/vuejs/vitepress/blob/main/types/default-theme.d.ts) interface for details on customizing the placeholder texts of the default theme. Don't override `themeConfig.algolia` or `themeConfig.carbonAds` at locale-level. Refer [Algolia docs](../reference/default-theme-search#i18n) for using multilingual search.
**Pro tip:** Config file can be stored at `docs/.vitepress/config/index.ts` too. It might help you organize stuff by creating a configuration file per locale and then merge and export them from `index.ts`. **Pro tip:** Config file can be stored at `docs/.vitepress/config/index.ts` too. It might help you organize stuff by creating a configuration file per locale and then to merge and export them from `index.ts`.
## Separate directory for each locale ## Separate directory for each locale
@ -75,7 +75,7 @@ However, VitePress won't redirect `/` to `/en/` by default. You'll need to confi
/* /en/:splat 302 /* /en/:splat 302
``` ```
**Pro tip:** If using the above approach, you can use `nf_lang` cookie to persist user's language choice: **Pro tip:** If using the above approach, you can use `nf_lang` cookie to make the user's language choice persistent:
```ts ```ts
// docs/.vitepress/theme/index.ts // docs/.vitepress/theme/index.ts

30
docs/en/guide/markdown.md
Unescape View File

@ -1,6 +1,6 @@
# Markdown Extensions # Markdown Extensions
VitePress comes with built in Markdown Extensions. VitePress comes with built-in Markdown Extensions.
## Header Anchors ## Header Anchors
@ -22,7 +22,7 @@ Both internal and external links get special treatment.
### Internal Links ### Internal Links
Internal links are converted to router link for SPA navigation. Also, every `index.md` contained in each sub-directory will automatically be converted to `index.html`, with corresponding URL `/`. Internal links are converted to router links for SPA navigation. Also, every `index.md` contained in each sub-directory will automatically be converted to `index.html`, with the corresponding URL `/`.
For example, given the following directory structure: For example, given the following directory structure:
@ -178,7 +178,7 @@ This is a details block.
### Custom Title ### Custom Title
You may set custom title by appending the text right after the "type" of the container. You may set a custom title by appending the text right after the "type" of the container.
**Input** **Input**
@ -206,7 +206,7 @@ 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: Also, you may set custom titles globally by adding the following content to your site config, helpful if not writing in English:
```ts ```ts
// config.ts // config.ts
@ -323,7 +323,7 @@ VitePress also supports [GitHub-flavored alerts](https://docs.github.com/en/get-
## Syntax Highlighting in Code Blocks ## Syntax Highlighting in Code Blocks
VitePress uses [Shiki](https://github.com/shikijs/shiki) to highlight language syntax in Markdown code blocks, using coloured text. Shiki supports a wide variety of programming languages. All you need to do is append a valid language alias to the beginning backticks for the code block: VitePress uses [Shiki](https://github.com/shikijs/shiki) to highlight language syntax in Markdown code blocks, using colored text. Shiki supports a wide variety of programming languages. All you need to do is append a valid language alias to the beginning backticks for the code block:
**Input** **Input**
@ -365,7 +365,7 @@ export default {
A [list of valid languages](https://shiki.style/languages) is available on Shiki's repository. A [list of valid languages](https://shiki.style/languages) is available on Shiki's repository.
You may also customize syntax highlight theme in app config. Please see [`markdown` options](../reference/site-config#markdown) for more details. You may also customize the syntax highlighting theme in the app config. Please see [`markdown` options](../reference/site-config#markdown) for more details.
## Line Highlighting in Code Blocks ## Line Highlighting in Code Blocks
@ -467,7 +467,7 @@ export default {
Adding the `// [!code focus]` comment on a line will focus it and blur the other parts of the code. Adding the `// [!code focus]` comment on a line will focus it and blur the other parts of the code.
Additionally, you can define a number of lines to focus using `// [!code focus:<lines>]`. Additionally, you can define a set number of lines to place in focus using `// [!code focus:<lines>]`.
**Input** **Input**
@ -497,7 +497,7 @@ export default {
## Colored Diffs in Code Blocks ## Colored Diffs in Code Blocks
Adding the `// [!code --]` or `// [!code ++]` comments on a line will create a diff of that line, while keeping the colors of the codeblock. Adding the `// [!code --]` or `// [!code ++]` comments on a line will create a diff of that line while keeping the colors of the code-block.
**Input** **Input**
@ -561,7 +561,7 @@ export default {
## Line Numbers ## Line Numbers
You can enable line numbers for each code blocks via config: You can enable line numbers for all code blocks via config:
```js ```js
export default { export default {
@ -573,7 +573,7 @@ export default {
Please see [`markdown` options](../reference/site-config#markdown) for more details. Please see [`markdown` options](../reference/site-config#markdown) for more details.
You can add `:line-numbers` / `:no-line-numbers` mark in your fenced code blocks to override the value set in config. You can add a `:line-numbers` / `:no-line-numbers` mark into your fenced code blocks as needed to override the value set in the 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`. 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`.
@ -621,7 +621,7 @@ const line4 = 'This is line 4'
## Import Code Snippets ## Import Code Snippets
You can import code snippets from existing files via following syntax: You can import code snippets from existing files via the following syntax:
```md ```md
<<< @/filepath <<< @/filepath
@ -648,7 +648,7 @@ It also supports [line highlighting](#line-highlighting-in-code-blocks):
<<< @/snippets/snippet.js{2} <<< @/snippets/snippet.js{2}
::: tip ::: 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: 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:
```md ```md
<<< ../snippets/snippet.js <<< ../snippets/snippet.js
@ -656,7 +656,7 @@ The value of `@` corresponds to the source root. By default it's the VitePress p
::: :::
You can also use a [VS Code region](https://code.visualstudio.com/docs/editor/codebasics#_folding) to only include the corresponding part of the code file. You can provide a custom region name after a `#` following the filepath: You can also use a [VS Code region](https://code.visualstudio.com/docs/editor/codebasics#_folding) to only include the corresponding part of the code file. You can provide a custom region name after a `#` following the base filepath:
**Input** **Input**
@ -686,7 +686,7 @@ You can also specify the language inside the braces (`{}`) like this:
<<< @/snippets/snippet.cs{1,2,4-6 c#:line-numbers} <<< @/snippets/snippet.cs{1,2,4-6 c#:line-numbers}
``` ```
This is helpful if source language cannot be inferred from your file extension. This is helpful if a source language cannot be inferred from your file extension.
## Code Groups ## Code Groups
@ -986,4 +986,4 @@ export default defineConfig({
}) })
``` ```
See full list of configurable properties in [Config Reference: App Config](../reference/site-config#markdown). You can full list of configurable properties on the [Config Reference: App Config](../reference/site-config#markdown) page.

14
docs/en/guide/migration-from-vitepress-0.md
Unescape View File

@ -1,6 +1,6 @@
# Migration from VitePress 0.x # Migration from VitePress 0.x
If you're coming from VitePress 0.x version, there're several breaking changes due to new features and enhancement. Please follow this guide to see how to migrate your app over to the latest VitePress. If you're coming from a VitePress 0.x version, there are several breaking changes due to new features and enhancements. Please follow this guide to see how to migrate your app over to the latest VitePress.
## App Config ## App Config
@ -10,14 +10,14 @@ If you're coming from VitePress 0.x version, there're several breaking changes d
- `sidebar` option has changed its structure. - `sidebar` option has changed its structure.
- `children` key is now named `items`. - `children` key is now named `items`.
- Top level item may not contain `link` at the moment. We're planning to bring it back. - Top-level items may not contain `link` at the moment. We're planning to bring it back.
- `repo`, `repoLabel`, `docsDir`, `docsBranch`, `editLinks`, `editLinkText` are removed in favor of more flexible api. - `repo`, `repoLabel`, `docsDir`, `docsBranch`, `editLinks`, `editLinkText` are removed in favor of more flexible api.
- For adding GitHub link with icon to the nav, use [Social Links](../reference/default-theme-nav#navigation-links) feature. - For adding GitHub link(s) with icon(s) to the nav, use the [Social Links](../reference/default-theme-nav#navigation-links) feature.
- For adding "Edit this page" feature, use [Edit Link](../reference/default-theme-edit-link) feature. - For adding "Edit this page" feature, use the [Edit Link](../reference/default-theme-edit-link) feature.
- `lastUpdated` option is now split into `config.lastUpdated` and `themeConfig.lastUpdatedText`. - The `lastUpdated` option is now split into `config.lastUpdated` and `themeConfig.lastUpdatedText`.
- `carbonAds.carbon` is changed to `carbonAds.code`. - `carbonAds.carbon` is changed to `carbonAds.code`.
## Frontmatter Config ## Frontmatter Config
- `home: true` option has changed to `layout: home`. Also, many Homepage related settings have been modified to provide additional features. See [Home Page guide](../reference/default-theme-home-page) for details. - The `home: true` option has changed to `layout: home`. In addition, many Homepage-related settings have been modified to provide additional features. See [Home Page guide](../reference/default-theme-home-page) for details.
- `footer` option is moved to [`themeConfig.footer`](../reference/default-theme-config#footer). - The `footer` option has moved to [`themeConfig.footer`](../reference/default-theme-config#footer).

6
docs/en/guide/migration-from-vuepress.md
Unescape View File

@ -10,9 +10,9 @@ The sidebar is no longer automatically populated from frontmatter. You can [read
### Images ### Images
Unlike VuePress, VitePress handles [`base`](./asset-handling#base-url) of your config automatically when you use static image. Unlike VuePress, VitePress handles [`base`](./asset-handling#base-url) of your config automatically when you use a static image.
Hence, now you can render images without `img` tag. As a result, you can render images without needing an `img` tag.
```diff ```diff
- <img :src="$withBase('/foo.png')" alt="foo"> - <img :src="$withBase('/foo.png')" alt="foo">
@ -20,7 +20,7 @@ Hence, now you can render images without `img` tag.
``` ```
::: warning ::: warning
For dynamic images you still need `withBase` as shown in [Base URL guide](./asset-handling#base-url). For dynamic images, you still need `withBase` as shown in [Base URL guide](./asset-handling#base-url).
::: :::
Use `<img.*withBase\('(.*)'\).*alt="([^"]*)".*>` regex to find and replace it with `![$2]($1)` to replace all the images with `![](...)` syntax. Use `<img.*withBase\('(.*)'\).*alt="([^"]*)".*>` regex to find and replace it with `![$2]($1)` to replace all the images with `![](...)` syntax.

10
docs/en/guide/mpa-mode.md
Unescape View File

@ -1,12 +1,12 @@
# MPA Mode <Badge type="warning" text="experimental" /> # MPA Mode <Badge type="warning" text="experimental" />
MPA (Multi-Page Application) mode can be enabled via the command line via `vitepress build --mpa`, or via config through the `mpa: true` option. MPA (Multi-Page Application) mode can be enabled via the command line by running `vitepress build --mpa`, or through config via the `mpa: true` option.
In MPA mode, all pages are rendered without any JavaScript included by default. As a result, the production site will likely have a better initial visit performance score from audit tools. In MPA mode, all pages are rendered without any JavaScript included by default. As a result, the production site will likely have a better initial visit performance score from audit tools.
However, due to the absence of SPA navigation, cross-page links will lead to full page reloads. Post-load navigations in MPA mode will not feel as instant as in SPA mode. However, due to the absence of SPA navigation, cross-page links will lead to full-page reloads. Post-load navigations in MPA mode will not feel as instant as in SPA mode.
Also note that no-JS-by-default means you are essentially using Vue purely as a server-side templating language. No event handlers will be attached in the browser, so there will be no interactivity. To load client-side JavaScript, you will need to use the special `<script client>` tag: It should also be noted that no-JS-by-default means you are essentially using Vue purely as a server-side templating language. No event handlers will be attached in the browser, so there will be no interactivity. To load client-side JavaScript, you will need to use the special `<script client>` tag:
```html ```html
<script client> <script client>
@ -18,6 +18,6 @@ document.querySelector('h1').addEventListener('click', () => {
# Hello # Hello
``` ```
`<script client>` is a VitePress-only feature, not a Vue feature. It works in both `.md` and `.vue` files, but only in MPA mode. Client scripts in all theme components will be bundled together, while client script for a specific page will be split for that page only. `<script client>` is a VitePress-only feature, not a Vue feature. It works in both `.md` and `.vue` files, but only in MPA mode. Client scripts in all theme components will be bundled together, while client scripts for a specific page will be split for that page only.
Note that `<script client>` is **not evaluated as Vue component code**: it's processed as a plain JavaScript module. For this reason, MPA mode should only be used if your site requires absolutely minimal client-side interactivity. Note that `<script client>` is **not evaluated as Vue component code**: it's processed as a plain JavaScript module. For this reason, MPA mode should only be used if your site requires either no interactivity or absolutely minimal client-side interactivity.

20
docs/en/guide/routing.md
Unescape View File

@ -6,7 +6,7 @@ outline: deep
## File-Based Routing ## File-Based Routing
VitePress uses file-based routing, which means the generated HTML pages are mapped from the directory structure of the source Markdown files. For example, given the following directory structure: VitePress uses file-based routing, which means that generated HTML pages are mapped from the directory structure of the source Markdown files. For example, given the following directory structure:
``` ```
. .
@ -34,9 +34,9 @@ There are two important concepts in the file structure of a VitePress project: t
### Project Root ### Project Root
Project root is where VitePress will try to look for the `.vitepress` special directory. The `.vitepress` directory is a reserved location for VitePress' config file, dev server cache, build output, and optional theme customization code. Project root is where VitePress will try to look for the `.vitepress` special directory. The `.vitepress` directory is a reserved location for the VitePress config file, dev server cache, build output, and optional theme customization code.
When you run `vitepress dev` or `vitepress build` from the command line, VitePress will use the current working directory as project root. To specify a sub-directory as root, you will need to pass the relative path to the command. For example, if your VitePress project is located in `./docs`, you should run `vitepress dev docs`: When you run `vitepress dev` or `vitepress build` from the command line, VitePress will use the current working directory as the project root. To specify a sub-directory as root, you will need to pass the relative path to the command. For example, if your VitePress project is located in `./docs`, you should run `vitepress dev docs`:
``` ```
. .
@ -60,9 +60,9 @@ docs/getting-started.md --> /getting-started.html
### Source Directory ### Source Directory
Source directory is where your Markdown source files live. By default, it is the same as the project root. However, you can configure it via the [`srcDir`](../reference/site-config#srcdir) config option. The Source Directory is where your Markdown source files live. By default, it is the same as the project root. However, you can configure it via the [`srcDir`](../reference/site-config#srcdir) config option.
The `srcDir` option is resolved relative to project root. For example, with `srcDir: 'src'`, your file structure will look like this: The `srcDir` option is resolved relative to the project root. For example, with `srcDir: 'src'`, your file structure will look like this:
``` ```
. # project root . # project root
@ -93,7 +93,7 @@ You can use both absolute and relative paths when linking between pages. Note th
[Getting Started](./getting-started.html) [Getting Started](./getting-started.html)
``` ```
Learn more about linking to assets such images in [Asset Handling](./asset-handling). You can learn more about linking to assets such as images in [Asset Handling](./asset-handling).
### Linking to Non-VitePress Pages ### Linking to Non-VitePress Pages
@ -137,7 +137,7 @@ Some servers or hosting platforms (for example Netlify, Vercel, GitHub Pages) pr
If this feature is available to you, you can then also enable VitePress' own [`cleanUrls`](../reference/site-config#cleanurls) config option so that: If this feature is available to you, you can then also enable VitePress' own [`cleanUrls`](../reference/site-config#cleanurls) config option so that:
- Inbound links between pages are generated without the `.html` extension. - Inbound links between pages are generated without the `.html` extension.
- If current path ends with `.html`, the router will perform a client-side redirect to the extension-less path. - If the current path ends with `.html`, the router will perform a client-side redirect to the extension-less path.
If, however, you cannot configure your server with such support, you will have to manually resort to the following directory structure: If, however, you cannot configure your server with such support, you will have to manually resort to the following directory structure:
@ -152,7 +152,7 @@ If, however, you cannot configure your server with such support, you will have t
## Route Rewrites ## Route Rewrites
You can customize the mapping between the source directory structure and the generated pages. It's useful when you have a complex project structure. For example, let's say you have a monorepo with multiple packages, and would like to place documentations along with the source files like this: You can customize the mapping between the source directory structure and the generated pages. It's useful when you have a complex project structure. For example, let's say you have a monorepo with multiple packages, and would like to place documentation files along with the source files like this:
``` ```
. .
@ -214,7 +214,7 @@ export default {
::: warning Relative Links with Rewrites ::: warning Relative Links with Rewrites
When rewrites are enabled, **relative links should be based on the rewritten paths**. For example, in order to create a relative link from `packages/pkg-a/src/pkg-a-code.md` to `packages/pkg-b/src/pkg-b-code.md`, you should use: When rewrites are enabled, **relative links should be based on the rewritten paths**. For example, to create a relative link from `packages/pkg-a/src/pkg-a-code.md` to `packages/pkg-b/src/pkg-b-code.md`, you should use:
```md ```md
[Link to PKG B](../pkg-b/pkg-b-code) [Link to PKG B](../pkg-b/pkg-b-code)
@ -361,7 +361,7 @@ console.log(params.value)
### Rendering Raw Content ### Rendering Raw Content
Params passed to the page will be serialized in the client JavaScript payload, so you should avoid passing heavy data in params, for example raw Markdown or HTML content fetched from a remote CMS. Params passed to the page will be serialized in the client JavaScript payload, so you should avoid passing heavy data in params, for example, raw Markdown or HTML content fetched from a remote CMS.
Instead, you can pass such content to each page using the `content` property on each path object: Instead, you can pass such content to each page using the `content` property on each path object:

2
docs/en/guide/ssr-compat.md
Unescape View File

@ -4,7 +4,7 @@ outline: deep
# SSR Compatibility # SSR Compatibility
VitePress pre-renders the app in Node.js during the production build, using Vue's Server-Side Rendering (SSR) capabilities. This means all custom code in theme components are subject to SSR Compatibility. VitePress pre-renders the app in Node.js during the production build, using Vue's Server-Side Rendering (SSR) capabilities. This means all custom code in theme components is subject to SSR Compatibility.
The [SSR section in official Vue docs](https://vuejs.org/guide/scaling-up/ssr.html) provides more context on what SSR is, the relationship between SSR / SSG, and common notes on writing SSR-friendly code. The rule of thumb is to only access browser / DOM APIs in `beforeMount` or `mounted` hooks of Vue components. The [SSR section in official Vue docs](https://vuejs.org/guide/scaling-up/ssr.html) provides more context on what SSR is, the relationship between SSR / SSG, and common notes on writing SSR-friendly code. The rule of thumb is to only access browser / DOM APIs in `beforeMount` or `mounted` hooks of Vue components.

8
docs/en/guide/using-vue.md
Unescape View File

@ -71,7 +71,7 @@ The count is: {{ count }}
When used in Markdown, `<style scoped>` requires adding special attributes to every element on the current page, which will significantly bloat the page size. `<style module>` is preferred when locally-scoped styling is needed in a page. When used in Markdown, `<style scoped>` requires adding special attributes to every element on the current page, which will significantly bloat the page size. `<style module>` is preferred when locally-scoped styling is needed in a page.
::: :::
You also have access to VitePress' runtime APIs such as the [`useData` helper](../reference/runtime-api#usedata), which provides access to current page's metadata: You also have access to VitePress' runtime APIs such as the [`useData` helper](../reference/runtime-api#usedata), which provides access to the current page's metadata:
**Input** **Input**
@ -122,7 +122,7 @@ This is a .md using a custom component
### Registering Components Globally ### Registering Components Globally
If a component is going to be used on most of the pages, they can be registered globally by customizing the Vue app instance. See relevant section in [Extending Default Theme](./extending-default-theme#registering-global-components) for an example. If a component is going to be used on several pages, it may be most useful to make it registered globally by customizing the Vue app instance. See the relevant section in [Extending Default Theme](./extending-default-theme#registering-global-components) for an example.
::: warning IMPORTANT ::: warning IMPORTANT
Make sure a custom component's name either contains a hyphen or is in PascalCase. Otherwise, it will be treated as an inline element and wrapped inside a `<p>` tag, which will lead to hydration mismatch because `<p>` does not allow block elements to be placed inside it. Make sure a custom component's name either contains a hyphen or is in PascalCase. Otherwise, it will be treated as an inline element and wrapped inside a `<p>` tag, which will lead to hydration mismatch because `<p>` does not allow block elements to be placed inside it.
@ -196,7 +196,7 @@ Hello {{ 1 + 1 }}
Hello {{ 1 + 1 }} Hello {{ 1 + 1 }}
``` ```
Note that this might prevent certain tokens from being syntax highlighted properly. Note that this may prevent certain tokens from being syntax-highlighted properly.
## Using CSS Pre-processors ## Using CSS Pre-processors
@ -224,7 +224,7 @@ Then you can use the following in Markdown and theme components:
## Using Teleports ## Using Teleports
VitePress currently has SSG support for teleports to body only. For other targets, you can wrap them inside the built-in `<ClientOnly>` component or inject the teleport markup into the correct location in your final page HTML through [`postRender` hook](../reference/site-config#postrender). VitePress currently has SSG support for teleports to the page body only. For other targets, you can wrap them inside the built-in `<ClientOnly>` component or inject the teleport markup into the correct location in your final page HTML through [`postRender` hook](../reference/site-config#postrender).
<ModalDemo /> <ModalDemo />

6
docs/en/guide/what-is-vitepress.md
Unescape View File

@ -30,11 +30,11 @@ VitePress aims to provide a great Developer Experience (DX) when working with Ma
- **[Built-in Markdown Extensions:](./markdown)** Frontmatter, tables, syntax highlighting... you name it. Specifically, VitePress provides many advanced features for working with code blocks, making it ideal for highly technical documentation. - **[Built-in Markdown Extensions:](./markdown)** Frontmatter, tables, syntax highlighting... you name it. Specifically, VitePress provides many advanced features for working with code blocks, making it ideal for highly technical documentation.
- **[Vue-Enhanced Markdown:](./using-vue)** each Markdown page is also a Vue [Single-File Component](https://vuejs.org/guide/scaling-up/sfc.html), thanks to Vue template's 100% syntax compatibility with HTML. You can embed interactivity in your static content using Vue templating features or imported Vue components. - **[Vue-Enhanced Markdown:](./using-vue)** Each Markdown page is also a Vue [Single-File Component](https://vuejs.org/guide/scaling-up/sfc.html), thanks to Vue templates' 100% syntax compatibility with HTML. You can embed interactivity in your static content using Vue templating features or imported Vue components.
## Performance ## Performance
Unlike many traditional SSGs where each navigation results in a full page reload, a website generated by VitePress serves static HTML on the initial visit, but becomes a [Single Page Application](https://en.wikipedia.org/wiki/Single-page_application) (SPA) for subsequent navigation within the site. This model, in our opinion, provides an optimal balance for performance: Unlike many traditional SSGs where each navigation results in a full page reload, a website generated by VitePress serves static HTML on the initial visit, then becomes a [Single Page Application](https://en.wikipedia.org/wiki/Single-page_application) (SPA) for subsequent navigation within the site. This model, in our opinion, provides an optimal balance for performance:
- **Fast Initial Load** - **Fast Initial Load**
@ -42,7 +42,7 @@ Unlike many traditional SSGs where each navigation results in a full page reload
- **Fast Post-load Navigation** - **Fast Post-load Navigation**
More importantly, the SPA model leads to better user experience **after** the initial load. Subsequent navigation within the site will no longer cause a full page reload. Instead, the incoming page's content will be fetched and dynamically updated. VitePress also automatically pre-fetches page chunks for links that are within viewport. In most cases, post-load navigation will feel instant. More importantly, the SPA model leads to a better user experience **after** the initial load. Subsequent navigation within the site will no longer cause a full page reload. Instead, the incoming page's content will be fetched and dynamically updated. VitePress also automatically pre-fetches page chunks for links that are within the viewport. In most cases, post-load navigation will feel instant.
- **Interactivity Without Penalty** - **Interactivity Without Penalty**

4
docs/en/reference/cli.md
Unescape View File

@ -2,7 +2,7 @@
## `vitepress dev` ## `vitepress dev`
Start VitePress dev server using designated directory as root. Defaults to current directory. The `dev` command can also be omitted when running in current directory. Starts a VitePress dev server using the designated directory as root. Defaults to current directory. The `dev` command can also be omitted when running in the current directory.
### Usage ### Usage
@ -65,7 +65,7 @@ vitepress preview [root]
## `vitepress init` ## `vitepress init`
Start the [Setup Wizard](../guide/getting-started#setup-wizard) in current directory. Starts the [Setup Wizard](../guide/getting-started#setup-wizard) in the current directory.
### Usage ### Usage

8
docs/en/reference/default-theme-badge.md
Unescape View File

@ -1,6 +1,6 @@
# Badge # Badge
The badge lets you add status to your headers. For example, it could be useful to specify the section's type, or supported version. The badge lets you add status to your headers. For example, it could be useful to specify the section's type or supported version.
## Usage ## Usage
@ -13,7 +13,7 @@ You may use the `Badge` component which is globally available.
### Title <Badge type="danger" text="caution" /> ### Title <Badge type="danger" text="caution" />
``` ```
Code above renders like: The above code renders as:
### Title <Badge type="info" text="default" /> ### Title <Badge type="info" text="default" />
### Title <Badge type="tip" text="^1.9.0" /> ### Title <Badge type="tip" text="^1.9.0" />
@ -22,7 +22,7 @@ Code above renders like:
## Custom Children ## Custom Children
`<Badge>` accept `children`, which will be displayed in the badge. `<Badge>` accepts `children`, which will be displayed inside of the badge.
```html ```html
### Title <Badge type="info">custom element</Badge> ### Title <Badge type="info">custom element</Badge>
@ -56,7 +56,7 @@ You can customize the style of badges by overriding css variables. The following
## `<Badge>` ## `<Badge>`
`<Badge>` component accepts following props: The `<Badge>` component accepts the following properties:
```ts ```ts
interface Props { interface Props {

6
docs/en/reference/default-theme-carbon-ads.md
Unescape View File

@ -1,6 +1,6 @@
# Carbon Ads # Carbon Ads
VitePress has built in native support for [Carbon Ads](https://www.carbonads.net/). By defining the Carbon Ads credentials in config, VitePress will display ads on the page. VitePress has built-in native support for [Carbon Ads](https://www.carbonads.net/). By defining the Carbon Ads credentials in the config, VitePress will display ads on the page.
```js ```js
export default { export default {
@ -13,10 +13,10 @@ export default {
} }
``` ```
These values are used to call carbon CDN script as shown below. These values are used to call the carbon CDN script, as shown below:
```js ```js
`//cdn.carbonads.com/carbon.js?serve=${code}&placement=${placement}` `//cdn.carbonads.com/carbon.js?serve=${code}&placement=${placement}`
``` ```
To learn more about Carbon Ads configuration, please visit [Carbon Ads website](https://www.carbonads.net/). To learn more about Carbon Ads configuration, please visit the [Carbon Ads website](https://www.carbonads.net/).

28
docs/en/reference/default-theme-config.md
Unescape View File

@ -17,19 +17,19 @@ export default {
} }
``` ```
**The options documented on this page only apply to the default theme.** Different themes expect different theme config. When using a custom theme, the theme config object will be passed to the theme so the theme can define conditional behavior based on it. **The options documented on this page only apply to the default theme.** Different themes expect different theme configurations. When using a custom theme, the theme config object will be passed to the theme so the theme can define conditional behavior based on it.
## i18nRouting ## i18nRouting
- Type: `boolean` - Type: `boolean`
Changing locale to say `zh` will change the URL from `/foo` (or `/en/foo/`) to `/zh/foo`. You can disable this behavior by setting `themeConfig.i18nRouting` to `false`. Changing the locale to say `zh` will change the URL from `/foo` (or `/en/foo/`) to `/zh/foo`. You can disable this behavior by setting `themeConfig.i18nRouting` to `false`.
## logo ## logo
- Type: `ThemeableImage` - Type: `ThemeableImage`
Logo file to display in nav bar, right before the site title. Accepts a path string, or an object to set a different logo for light/dark mode. Sets a Logo file to display in the nav bar, right before the site title. Accepts a path string, or an object to set a different logo for light/dark mode.
```ts ```ts
export default { export default {
@ -50,7 +50,7 @@ type ThemeableImage =
- Type: `string | false` - Type: `string | false`
You can customize this item to replace the default site title (`title` in app config) in nav. When set to `false`, title in nav will be disabled. Useful when you have `logo` that already contains the site title text. You can customize this item to replace the default site title (`title` in app config) in nav. When set to `false`, the title in nav will be disabled. Useful when you have `logo` that already contains the site title text.
```ts ```ts
export default { export default {
@ -64,7 +64,7 @@ export default {
- Type: `NavItem` - Type: `NavItem`
The configuration for the nav menu item. More details in [Default Theme: Nav](./default-theme-nav#navigation-links). The configuration for the nav menu item. More details can be found in the [Default Theme: Nav](./default-theme-nav#navigation-links) article.
```ts ```ts
export default { export default {
@ -112,7 +112,7 @@ interface NavItemWithChildren {
- Type: `Sidebar` - Type: `Sidebar`
The configuration for the sidebar menu item. More details in [Default Theme: Sidebar](./default-theme-sidebar). The configuration for the sidebar menu item. More details can be found in the [Default Theme: Sidebar](./default-theme-sidebar) article.
```ts ```ts
export default { export default {
@ -195,7 +195,7 @@ If you want to disable it for all viewports, you should use `outline: false` ins
- Type: `Outline | Outline['level'] | false` - Type: `Outline | Outline['level'] | false`
- Level can be overridden per page via [frontmatter](./frontmatter-config#outline) - Level can be overridden per page via [frontmatter](./frontmatter-config#outline)
Setting this value to `false` prevents rendering of outline container. Refer this interface for more details: Setting this value to `false` prevents the rendering of outline containers. Refer to this interface for more details:
```ts ```ts
interface Outline { interface Outline {
@ -222,7 +222,7 @@ interface Outline {
- Type: `SocialLink[]` - Type: `SocialLink[]`
You may define this option to show your social account links with icons in nav. Setting a definition for this config option will show the provided social account links with icons (if included/provided) in nav.
```ts ```ts
export default { export default {
@ -342,7 +342,7 @@ export interface LastUpdatedOptions {
- Type: `AlgoliaSearch` - Type: `AlgoliaSearch`
An option to support searching your docs site using [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Learn more in [Default Theme: Search](./default-theme-search) A toggleable option to support searching your docs site using [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Learn more on the [Default Theme: Search](./default-theme-search) page.
```ts ```ts
export interface AlgoliaSearchOptions extends DocSearchProps { export interface AlgoliaSearchOptions extends DocSearchProps {
@ -350,7 +350,7 @@ export interface AlgoliaSearchOptions extends DocSearchProps {
} }
``` ```
View full options [here](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts). You can view a full list of all options [here](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts).
## carbonAds {#carbon-ads} ## carbonAds {#carbon-ads}
@ -376,7 +376,7 @@ export interface CarbonAdsOptions {
} }
``` ```
Learn more in [Default Theme: Carbon Ads](./default-theme-carbon-ads) Learn more on the [Default Theme: Carbon Ads](./default-theme-carbon-ads) page.
## docFooter ## docFooter
@ -414,7 +414,7 @@ Can be used to customize the dark mode switch label. This label is only displaye
- Type: `string` - Type: `string`
- Default: `Switch to light theme` - Default: `Switch to light theme`
Can be used to customize the light mode switch title that appears on hovering. Can be used to customize the light mode switch title that appears when hovering over it.
## darkModeSwitchTitle ## darkModeSwitchTitle
@ -442,7 +442,7 @@ Can be used to customize the label of the return to top button. This label is on
- Type: `string` - Type: `string`
- Default: `Change language` - Default: `Change language`
Can be used to customize the aria-label of the language toggle button in navbar. This is only used if you're using [i18n](../guide/i18n). Allows for customization of the aria-label of the language toggle button on the navbar. This is only used if you're using [i18n](../guide/i18n).
## skipToContentLabel ## skipToContentLabel
@ -456,4 +456,4 @@ Can be used to customize the label of the skip to content link. This link is sho
- Type: `boolean` - Type: `boolean`
- Default: `false` - Default: `false`
Whether to show an external link icon next to external links in markdown. Toggles whether to show an external link icon next to external links in markdown.

10
docs/en/reference/default-theme-edit-link.md
Unescape View File

@ -2,7 +2,7 @@
## Site-Level Config ## Site-Level Config
Edit Link lets you display a link to edit the page on Git management services such as GitHub, or GitLab. To enable it, add `themeConfig.editLink` options to your config. The Edit Link option lets you display a link to edit the page on Git management services such as GitHub, or GitLab. To enable it, add the `themeConfig.editLink` option to your config.
```js ```js
export default { export default {
@ -14,9 +14,9 @@ export default {
} }
``` ```
The `pattern` option defines the URL structure for the link, and `:path` is going to be replaced with the page path. The `pattern` option defines the URL structure for the link, where `:path` will automatically be replaced with the page path.
You can also put a pure function that accepts [`PageData`](./runtime-api#usedata) as the argument and returns the URL string. You can also create a pure function that accepts [`PageData`](./runtime-api#usedata) as the argument to return the URL string.
```js ```js
export default { export default {
@ -34,7 +34,7 @@ export default {
} }
``` ```
It should not have side-effects nor access anything outside of its scope since it will be serialized and executed in the browser. This option should not have side effects nor access anything outside of its scope, as it is serialized and executed in the browser.
By default, this will add the link text "Edit this page" at the bottom of the doc page. You may customize this text by defining the `text` option. By default, this will add the link text "Edit this page" at the bottom of the doc page. You may customize this text by defining the `text` option.
@ -51,7 +51,7 @@ export default {
## Frontmatter Config ## Frontmatter Config
This can be disabled per-page using the `editLink` option on frontmatter: This can be disabled on a per-page basis using the `editLink` option on frontmatter:
```yaml ```yaml
--- ---

8
docs/en/reference/default-theme-footer.md
Unescape View File

@ -1,6 +1,6 @@
# Footer # Footer
VitePress will display global footer at the bottom of the page when `themeConfig.footer` is present. VitePress will display the global footer at the bottom of the page when `themeConfig.footer` is present.
```ts ```ts
export default { export default {
@ -37,14 +37,14 @@ export default {
``` ```
::: warning ::: warning
Only inline elements can be used in `message` and `copyright` as they are rendered inside a `<p>` element. If you want to add block elements, consider using [`layout-bottom`](../guide/extending-default-theme#layout-slots) slot instead. Only inline elements can be used in `message` and `copyright` as they are rendered inside a `<p>` element. If you want to add block elements, consider using the [`layout-bottom`](../guide/extending-default-theme#layout-slots) slot instead.
::: :::
Note that footer will not be displayed when the [SideBar](./default-theme-sidebar) is visible. Note that the footer will not be displayed when the [SideBar](./default-theme-sidebar) is visible.
## Frontmatter Config ## Frontmatter Config
This can be disabled per-page using the `footer` option on frontmatter: This can be disabled on a per-page basis using the `footer` option on frontmatter:
```yaml ```yaml
--- ---

16
docs/en/reference/default-theme-home-page.md
Unescape View File

@ -1,6 +1,6 @@
# Home Page # Home Page
VitePress default theme provides a homepage layout, which you can also see used on [the homepage of this site](../). You may use it on any of your pages by specifying `layout: home` in the [frontmatter](./frontmatter-config). VitePress' default theme provides a homepage layout, which you can also see used on [the homepage of this site](../). You may use it on any of your pages by specifying `layout: home` in the [frontmatter](./frontmatter-config).
```yaml ```yaml
--- ---
@ -8,7 +8,7 @@ layout: home
--- ---
``` ```
However, this option alone wouldn't do much. You can add several different pre templated "sections" to the homepage by setting additional other options such as `hero` and `features`. However, this option alone wouldn't do much. You can add several different pre-made template "sections" to the homepage by setting additional other options such as `hero` and `features`.
## Hero Section ## Hero Section
@ -37,8 +37,8 @@ hero:
```ts ```ts
interface Hero { interface Hero {
// The string shown top of `text`. Comes with brand color // The string shown top of `text`. Comes with the brand color
// and expected to be short, such as product name. // and expected to be short, such as a product name.
name?: string name?: string
// The main text for the hero section. This will be defined // The main text for the hero section. This will be defined
@ -51,7 +51,7 @@ interface Hero {
// The image is displayed next to the text and tagline area. // The image is displayed next to the text and tagline area.
image?: ThemeableImage image?: ThemeableImage
// Action buttons to display in home hero section. // Action buttons to display in the home hero section.
actions?: HeroAction[] actions?: HeroAction[]
} }
@ -88,7 +88,7 @@ VitePress uses the brand color (`--vp-c-brand-1`) for the `name`. However, you m
} }
``` ```
Also you may customize it further by combining `--vp-home-hero-name-background` to give the `name` gradient color. You may also customize it further by combining `--vp-home-hero-name-background` to give the `name` a gradient color.
```css ```css
:root { :root {
@ -99,9 +99,9 @@ Also you may customize it further by combining `--vp-home-hero-name-background`
## Features Section ## Features Section
In Features section, you can list any number of features you would like to show right after the Hero section. To configure it, pass `features` option to the frontmatter. In the Features section, you can list any number of features you would like to show right after the Hero section. To configure it, pass the `features` option to the frontmatter.
You can provide an icon for each feature, which can be an emoji or any type of image. When the configured icon is an image (svg, png, jpeg...), you must provide the icon with the proper width and height; you can also provide the description, its intrinsic size as well as its variants for dark and light theme when required. You can provide an icon for each feature, which can be an emoji or any type of image. When the configured icon is an image (svg, png, jpeg...), you must provide the icon with the proper width and height; you can also provide the description, its intrinsic size, as well as its variants for dark and light themes when required.
```yaml ```yaml
--- ---

6
docs/en/reference/default-theme-last-updated.md
Unescape View File

@ -1,6 +1,6 @@
# Last Updated # Last Updated
The update time of the last content will be displayed in the lower right corner of the page. To enable it, add `lastUpdated` options to your config. The update time of the last content will be displayed in the lower right-hand corner of the page. To enable it, add `lastUpdated` options to your config.
::: tip ::: tip
You need to commit the markdown file to see the updated time. You need to commit the markdown file to see the updated time.
@ -16,7 +16,7 @@ export default {
## Frontmatter Config ## Frontmatter Config
This can be disabled per-page using the `lastUpdated` option on frontmatter: This can be disabled on a per-page basis by using the `lastUpdated` option on frontmatter:
```yaml ```yaml
--- ---
@ -24,4 +24,4 @@ lastUpdated: false
--- ---
``` ```
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. Also refer to [Default Theme: Last Updated](./default-theme-config#lastupdated) for more details. Any truthy value at the theme level will also enable the feature unless explicitly disabled at the site or page level.

16
docs/en/reference/default-theme-layout.md
Unescape View File

@ -1,6 +1,6 @@
# Layout # Layout
You may choose the page layout by setting `layout` option to the page [frontmatter](./frontmatter-config). There are 3 layout options, `doc`, `page`, and `home`. If nothing is specified, then the page is treated as `doc` page. You may choose the page layout by setting the `layout` option to the page [frontmatter](./frontmatter-config). There are 3 layout options, `doc`, `page`, and `home`. If nothing is specified, then the page is treated as `doc` page.
```yaml ```yaml
--- ---
@ -10,11 +10,11 @@ layout: doc
## Doc Layout ## Doc Layout
Option `doc` is the default layout and it styles the whole Markdown content into "documentation" look. It works by wrapping whole content within `vp-doc` css class, and applying styles to elements underneath it. Option `doc` is the default layout and it styles the whole Markdown content into a "documentation" look. It works by wrapping whole content within `vp-doc` css class, and applying styles to elements underneath it.
Almost all generic elements such as `p`, or `h2` get special styling. Therefore, keep in mind that if you add any custom HTML inside a Markdown content, those will get affected by those styles as well. Almost all generic elements such as `p`, or `h2` get special styling. Therefore, keep in mind that if you add any custom HTML inside a Markdown content, those will get affected by those styles as well.
It also provides documentation specific features listed below. These features are only enabled in this layout. It also provides some documentation-specific features, which are listed below. These features are only enabled in this layout:
- Edit Link - Edit Link
- Prev Next Link - Prev Next Link
@ -23,19 +23,19 @@ It also provides documentation specific features listed below. These features ar
## Page Layout ## Page Layout
Option `page` is treated as "blank page". The Markdown will still be parsed, and all of the [Markdown Extensions](../guide/markdown) work as same as `doc` layout, but it wouldn't get any default stylings. Option `page` is treated as a "blank page". The Markdown will still be parsed, and all of the [Markdown Extensions](../guide/markdown) work as same as with the `doc` layout, but it wouldn't get any default stylings.
The page layout will let you style everything by you without VitePress theme affecting the markup. This is useful when you want to create your own custom page. The page layout will let you style everything yourself without the VitePress theme affecting the markup. This is useful when you want to create your own custom page.
Note that even in this layout, sidebar will still show up if the page has a matching sidebar config. Note that even in this layout, the sidebar will still show up if the page has a matching sidebar config.
## Home Layout ## Home Layout
Option `home` will generate templated "Homepage". In this layout, you can set extra options such as `hero` and `features` to customize the content further. Please visit [Default Theme: Home Page](./default-theme-home-page) for more details. Option `home` will generate a "Homepage" template. In this layout, you can set extra options such as `hero` and `features` to customize the content further. Please visit the [Default Theme: Home Page](./default-theme-home-page) page for more details.
## No Layout ## 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). 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 ## Custom Layout

Write Preview
Loading…
Cancel
Save