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
export default {
@ -19,4 +19,4 @@ These values are used to call carbon CDN script as shown below.
Theme config lets you customize your theme. You can define theme config via the `themeConfig` option in the config file:
The theme config lets you customize your theme. You can define it using the `themeConfig` option in the config file:
```ts
export default {
@ -8,7 +8,7 @@ export default {
title: 'VitePress',
description: 'Vite & Vue powered static site generator.',
// Theme related configurations.
// Theme related configuration.
themeConfig: {
logo: '/logo.svg',
nav: [...],
@ -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 will expect different theme options. When using a custom theme, the theme config object will be passed to the theme directly, so the theme can define conditional behavior based on it.
## i18nRouting
- 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 `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
- 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.
This is the logo file to display in the navigation bar, before the site title. It accepts a path string or an object to set a different logo for light/dark mode.
```ts
export default {
@ -50,7 +50,7 @@ type ThemeableImage =
- 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 navigation title will be disabled. This option is useful when you have a`logo` that already contains the site title text.
```ts
export default {
@ -64,7 +64,7 @@ export default {
- Type: `NavItem`
The configuration for the nav menu item. More details in [Default Theme: Nav](./default-theme-nav#navigation-links).
The configuration for navigation menu items. More details in [Default Theme: Nav](./default-theme-nav#navigation-links).
The configuration for the sidebar menu item. More details in [Default Theme: Sidebar](./default-theme-sidebar).
The configuration for sidebar menu items. More details in [Default Theme: Sidebar](./default-theme-sidebar).
```ts
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`
- 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 rendering of outline container. Refer to this interface for more details:
```ts
interface Outline {
@ -222,7 +222,7 @@ interface Outline {
- Type: `SocialLink[]`
You may define this option to show your social account links with icons in nav.
You can define this option to show social account links with icons in the navigation bar.
```ts
export default {
@ -256,9 +256,9 @@ interface SocialLink {
## footer
- Type: `Footer`
- Can be overridden per page via [frontmatter](./frontmatter-config#footer)
- Can be overridden per page using [frontmatter](./frontmatter-config#footer)
Footer configuration. You can add a message or copyright text on the footer, however, it will only be displayed when the page doesn't contain a sidebar. This is due to design concerns.
You can add a message and/or copyright text on the footer using this option. However, it will only be displayed when the page doesn't contain a sidebar, due to design concerns.
```ts
export default {
@ -283,7 +283,7 @@ export interface Footer {
- Type: `EditLink`
- Can be overridden per page via [frontmatter](./frontmatter-config#editlink)
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.
You can display a link to edit each documentation page at the bottom of the page. See [Default Theme: Edit Link](./default-theme-edit-link) for more details.
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)
An option to support searching your site with [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Learn more in [Default Theme: Search](./default-theme-search)
@ -382,7 +382,7 @@ Learn more in [Default Theme: Carbon Ads](./default-theme-carbon-ads)
- Type: `DocFooter`
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).
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 previous/next links per-page, you can use [frontmatter](./default-theme-prev-next-links).
```ts
export default {
@ -407,35 +407,35 @@ export interface DocFooter {
- Type: `string`
- Default: `Appearance`
Can be used to customize the dark mode switch label. This label is only displayed in the mobile view.
Can be used to customize the dark mode switch label. This label is only displayed on mobile.
## lightModeSwitchTitle
- Type: `string`
- 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 on hover.
## darkModeSwitchTitle
- Type: `string`
- Default: `Switch to dark theme`
Can be used to customize the dark mode switch title that appears on hovering.
Can be used to customize the dark mode switch title that appears on hover.
## sidebarMenuLabel
- Type: `string`
- Default: `Menu`
Can be used to customize the sidebar menu label. This label is only displayed in the mobile view.
Can be used to customize the sidebar menu label. This label is only displayed on mobile.
## returnToTopLabel
- Type: `string`
- Default: `Return to top`
Can be used to customize the label of the return to top button. This label is only displayed in the mobile view.
Can be used to customize the label of the return to top button. This label is only displayed on mobile.
## langMenuLabel
@ -456,7 +456,7 @@ Can be used to customize the label of the skip to content link. This link is sho
- Type: `boolean`
- Default: `false`
Whether to show an external link icon next to external links in markdown.
Whether to show an external link icon next to external links in Markdown.
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.
You can display a link to edit each documentation page at the bottom of the page. To enable it, add `themeConfig.editLink` options to your config.
```js
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, and the `:path` placeholder is 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 use a callback that takes [`PageData`](./runtime-api#usedata) as the argument and returns the URL string for additional customizability. This will be executed in the browser and hence shouldn't have side effects.
```js
export default {
@ -34,9 +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.
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 option will add the link text "Edit this page" at the bottom of the doc page. You can customize this text by defining the `text` option.
```js
export default {
@ -51,7 +49,7 @@ export default {
## Frontmatter Config
This can be disabled per-page using the `editLink` option on frontmatter:
This can be disabled per-page using the `editLink` option in each individual page's frontmatter:
VitePress will display global footer at the bottom of the page when `themeConfig.footer` is present.
VitePress will display a global footer at the bottom of the page when `themeConfig.footer` is present.
```ts
export default {
@ -15,7 +15,7 @@ export default {
```ts
export interface Footer {
// The message shown right before copyright.
// The message shown before the copyright.
message?: string
// The actual copyright text.
@ -23,7 +23,7 @@ export interface Footer {
}
```
The above configuration also supports HTML strings. So, for example, if you want to configure footer text to have some links, you can adjust the configuration as follows:
You can additionally directly embed HTML strings in the configuration if you want to add links or markup to the footer.
```ts
export default {
@ -37,14 +37,14 @@ export default {
```
::: 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.
You can only use inline elements 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.
## Frontmatter Config
This can be disabled per-page using the `footer` option on frontmatter:
This can be disabled per-page using the `footer` option in each individual page's frontmatter:
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's default theme provides a homepage layout, which looks like [this site's homepage](../). You can use it on any of your pages by specifying `layout: home` in the [frontmatter](./frontmatter-config).
```yaml
---
@ -8,11 +8,11 @@ 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`.
On its own, the option doesn't change much—you instead need to specify slots using the frontmatter that then get applied to the page.
## Hero Section
The Hero section comes at the top of the homepage. Here's how you can configure the Hero section.
The hero section is rendered at the top of the homepage:
```yaml
---
@ -37,21 +37,21 @@ hero:
```ts
interface Hero {
// The string shown top of `text`. Comes with brand color
// and expected to be short, such as product name.
// The string shown on top of `text`. Rendered with brand color
// and expected to be short, such as the product name.
name?: string
// The main text for the hero section. This will be defined
// as `h1` tag.
// as an `h1` tag.
text: string
// Tagline displayed below `text`.
tagline?: string
// The image is displayed next to the text and tagline area.
// Image displayed next to the text and tagline.
image?: ThemeableImage
// Action buttons to display in home hero section.
// Action buttons to display below text and image.
actions?: HeroAction[]
}
@ -64,10 +64,10 @@ interface HeroAction {
// Color theme of the button. Defaults to `brand`.
theme?: 'brand' | 'alt'
// Label of the button.
// Button label.
text: string
// Destination link of the button.
// Destination link for the button.
link: string
// Link target attribute.
@ -80,7 +80,7 @@ interface HeroAction {
### Customizing the name color
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.
By default, VitePress uses the brand color (`--vp-c-brand-1`) for the `name`. This can be customized by overriding `--vp-home-hero-name-color`.
```css
:root {
@ -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 can also customize the name further by combining it with `--vp-home-hero-name-background` for a gradient.
```css
:root {
@ -99,9 +99,9 @@ Also you may customize it further by combining `--vp-home-hero-name-background`
## 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 feature cards you want shown under the hero section. To enable 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 emoji or image icon for each feature. When the configured icon is an image (svg, png, jpeg, etc), you must provide the icon with a proper width and height. You can also provide a description, its intrinsic size, as well as variants for dark and light mode.
```yaml
---
@ -169,7 +169,7 @@ type FeatureIcon =
## Markdown Content
You can add additional content to your site's homepage just by adding Markdown below the `---` frontmatter divider.
You can add additional content to your site's homepage by adding Markdown below the `---` frontmatter divider.
````md
---
@ -191,5 +191,5 @@ npx vitepress init
````
::: info
VitePress didn't always auto-style the extra content of the `layout: home` page. To revert to older behavior, you can add `markdownStyles: false` to the frontmatter.
VitePress didn't always automatically style additional homepage content. To revert to the previously-used behavior, add `markdownStyles: false` to the frontmatter.
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.
You can show the last time content was updated in the lower right corner of the page. To enable it, add the`lastUpdated` options to your config.
::: info
VitePress displays the "last updated" time using the timestamp of the most recent Git commit for each file. To enable this, the Markdown file must be committed to Git.
@ -18,7 +18,7 @@ To fix this in **GitHub Actions**, use the following in your workflow:
Other CI/CD platforms have similar settings.
If such options aren't available, you can prepend the `docs:build` command in your `package.json` with a manual fetch:
If these options aren't available, you can prepend the `docs:build` command in your `package.json` with a manual fetch:
This can be disabled per-page using the `lastUpdated` option on frontmatter:
This can be disabled per-page using the `lastUpdated` option in each individual page's frontmatter:
```yaml
---
@ -43,4 +43,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.
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 can choose the page layout by setting the `layout` option on the page's [frontmatter](./frontmatter-config). There are three layout options: `doc`, `page`, and `home`. By default, pages use the `doc` layout.
```yaml
---
@ -10,32 +10,32 @@ layout: doc
## 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.
The `doc` option is the default layout and it styles the Markdown content to look like a documentation page. It wraps the whole content in the `vp-doc` CSS class, which applies styles to elements in 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 like `p` or `h2` have special styling, so keep in mind that custom HTML inside Markdown content will also get affected.
It also provides documentation specific features listed below. These features are only enabled in this layout.
It also provides documentation specific features, which are are only enabled when using this 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.
The `page` option is treated as as a blank page. Markdown will still be parsed, and all of the [Markdown Extensions](../guide/markdown) work the same as in the `doc` layout, but there is no default styling.
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.
This layout will let you style everything yourself without VitePress theming affecting the markup. This is useful for creating entirely custom pages.
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 configuration.
## 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.
The `home` option will generate a templated home page. With the default layout, you can set extra frontmatter options such as `hero` and `features` to customize the content further. Please read [Default Theme: Home Page](./default-theme-home-page) for more details.
## 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`in the frontmatter. This option is helpful if you want a fully-customizable landing page, without any sidebar, navbar, or footer.
## Custom Layout
@ -47,7 +47,7 @@ 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`:
This will look for a component named `foo` registered in context. You can register your component globally in `.vitepress/theme/index.ts`:
The Nav is the navigation bar displayed on top of the page. It contains the site title, global menu links, etc.
The Nav is the navigation bar displayed on top of the page. It contains the site title, global menu links, and the theme slider.
## Site Title and Logo
@ -24,7 +24,7 @@ export default {
}
```
When adding a logo, it gets displayed along with the site title. If your logo is all you need and if you would like to hide the site title text, set `false` to the `siteTitle` option.
When adding a logo, it gets displayed along with the site title. If your logo is all you need and if you would like to hide the site title text, set `siteTitle` to `false`.
```js
export default {
@ -35,11 +35,11 @@ export default {
}
```
You can also pass an object as logo if you want to add `alt` attribute or customize it based on dark/light mode. Refer [`themeConfig.logo`](./default-theme-config#logo) for details.
You can also pass an object as a logo if you want to add an`alt` attribute or customize it based on dark/light mode. Refer to [`themeConfig.logo`](./default-theme-config#logo) for more details.
## Navigation Links
You may define `themeConfig.nav` option to add links to your nav.
You can define the `themeConfig.nav` option to add links to your navigation bar.
```js
export default {
@ -53,9 +53,9 @@ export default {
}
```
The `text`is the actual text displayed in nav, and the `link` is the link that will be navigated to when the text is clicked. For the link, set path to the actual file without `.md` prefix, and always start with `/`.
The `text`will be the text displayed in nav, and the `link` is where the text will send you. Always start links with `/` and omit the `.md` suffix when linking to pages.
Nav links can also be dropdown menus. To do this, set `items` key on link option.
Nav links can also be dropdown menus. To do this, set the `items` key on the given link option.
```js
export default {
@ -75,9 +75,9 @@ export default {
}
```
Note that dropdown menu title (`Dropdown Menu` in the above example) can not have `link` property since it becomes a button to open dropdown dialog.
Note that the dropdown menu title (`Dropdown Menu` in the above example) can not have `link` property, since it becomes a button to open the dropdown dialog.
You may further add "sections" to the dropdown menu items as well by passing in more nested items.
You can add "sections" to the dropdown menu items as well by passing in more nested items.
```js
export default {
@ -101,7 +101,7 @@ export default {
text: 'Dropdown Menu',
items: [
{
// You may also omit the title.
// You can also omit the title.
items: [
{ text: 'Section A Item A', link: '...' },
{ text: 'Section B Item B', link: '...' }
@ -116,7 +116,7 @@ export default {
### Customize link's "active" state
Nav menu items will be highlighted when the current page is under the matching path. if you would like to customize the path to be matched, define `activeMatch` property and regex as a string value.
Navigation menu items will be highlighted when the current page is under the matching path. if you would like to customize the path to be matched, define the `activeMatch` property as a regular expression string.
```js
export default {
@ -135,12 +135,12 @@ export default {
```
::: warning
`activeMatch` is expected to be a regex string, but you must define it as a string. We can't use actual RegExp object here because it isn't serializable during the build time.
`activeMatch` is expected to be a regular expression, but you must define it as a string. We can't use an actual RegExp object here because it cannot be serialized during the build time.
:::
### Customize link's "target" and "rel" attributes
### Customize the link's "target" and "rel" attributes
By default, VitePress automatically determines `target` and `rel` attributes based on whether the link is an external link. But if you want, you can customize them too.
By default, VitePress tries to automatically determine the `target` and `rel` attributes based on whether the link is external or not. You can override this behavior by passing the options in directly.
You can customize the text and link for the previous and next pages (shown at doc footer). This is helpful if you want a different text there than what you have on your sidebar. Additionally, you may find it useful to disable the footer or link to a page that is not included in your sidebar.
You can customize the text and link for the previous and next pages (shown at doc footer). This is helpful if you want different text there than what's on the sidebar. Additionally, you may find it useful to disable the footer or link to a page that is not included in your sidebar.
## prev
@ -8,7 +8,7 @@ You can customize the text and link for the previous and next pages (shown at do
- Details:
Specifies the text/link to show on the link to the previous page. If you don't set this in frontmatter, the text/link will be inferred from the sidebar config.
Specifies the text/link to show on the link to the previous page. If you don't set this in frontmatter, the text/link will be inferred from the sidebar configuration.
- Examples:
@ -30,7 +30,7 @@ You can customize the text and link for the previous and next pages (shown at do
---
```
- To hide previous page:
- To hide the previous page link:
```yaml
---
@ -40,4 +40,4 @@ You can customize the text and link for the previous and next pages (shown at do
## next
Same as `prev` but for the next page.
`next` has the same interface and caveats as `prev`, but for the next page.
VitePress supports fuzzy full-text search using an in-browser index thanks to [minisearch](https://github.com/lucaong/minisearch/). To enable this feature, simply set the `themeConfig.search.provider` option to `'local'` in your `.vitepress/config.ts` file:
VitePress supports fuzzy full-text search using the [minisearch](https://github.com/lucaong/minisearch/) in-browser index. To enable this feature, simply set the `themeConfig.search.provider` option to `'local'` in your `.vitepress/config.ts` file:
```ts
import { defineConfig } from 'vitepress'
@ -24,7 +24,7 @@ Example result:
Alternatively, you can use [Algolia DocSearch](#algolia-search) or some community plugins like:
Alternatively, you can use [Algolia DocSearch](#algolia-search) or community plugins like:
@ -32,7 +32,7 @@ Alternatively, you can use [Algolia DocSearch](#algolia-search) or some communit
### i18n {#local-search-i18n}
You can use a config like this to use multilingual search:
You can use a configuration like this to enable multilingual search:
```ts
import { defineConfig } from 'vitepress'
@ -135,7 +135,7 @@ export default defineConfig({
})
```
This function will be stripped from client-side site data, so you can use Node.js APIs in it.
This function will be stripped from client-side site data, so you can use server-side APIs in it.
#### Example: Excluding pages from search
@ -189,7 +189,7 @@ export default defineConfig({
## Algolia Search
VitePress supports searching your docs site using [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Refer their getting started guide. In your `.vitepress/config.ts` you'll need to provide at least the following to make it work:
VitePress supports searching your docs site using [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Refer to their getting started guide. In your `.vitepress/config.ts`, you'll need to provide at least the following to make it work:
```ts
import { defineConfig } from 'vitepress'
@ -210,7 +210,7 @@ export default defineConfig({
### i18n {#algolia-search-i18n}
You can use a config like this to use multilingual search:
You can use a configuration like this to enable multilingual search:
```ts
import { defineConfig } from 'vitepress'
@ -303,7 +303,7 @@ export default defineConfig({
})
```
[These options](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts) can be overridden. Refer official Algolia docs to learn more about them.
[These options](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts) can be overridden. Refer to the official Algolia docs to learn more about them.
### Algolia Ask AI Support {#ask-ai}
@ -337,7 +337,7 @@ export default defineConfig({
```
::: warning Note
If want to default to keyword search and do not want to use Ask AI, just omit the `askAi` property
If you want to default to keyword search and not use Ask AI, just omit the `askAi` property
:::
The translations for the Ask AI UI live under `options.translations.modal.askAiScreen` and `options.translations.resultsScreen` — see the [type definitions](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts) for all keys.
The sidebar is the main navigation block for your documentation. You can configure the sidebar menu in [`themeConfig.sidebar`](./default-theme-config#sidebar).
The sidebar is the main navigation element for your documentation. You can configure the sidebar menu in [`themeConfig.sidebar`](./default-theme-config#sidebar).
```js
export default {
@ -21,7 +21,7 @@ export default {
## The Basics
The simplest form of the sidebar menu is passing in a single array of links. The first level item defines the "section" for the sidebar. It should contain `text`, which is the title of the section, and `items` which are the actual navigation links.
The simplest form of the sidebar menu is passing in a single array of links. The first level item defines the "section" for the sidebar. It should contain `text`, which is the title of the section, and `items`, which are the actual navigation links.
```js
export default {
@ -48,7 +48,7 @@ export default {
}
```
Each `link` should specify the path to the actual file starting with `/`. If you add trailing slash to the end of link, it will show `index.md` of the corresponding directory.
Each `link` should specify the path to the file starting with `/`. If you add a trailing slash to the end of link, it will show the `index.md` of the corresponding directory (much like HTML).
```js
export default {
@ -66,7 +66,7 @@ export default {
}
```
You may further nest the sidebar items up to 6 level deep counting up from the root level. Note that deeper than 6 level of nested items gets ignored and will not be displayed on the sidebar.
You can further nest the sidebar items up to six levels deep, counting up from the root level. Note that any items deeper than six level of nested items will be ignored and not displayed on the sidebar.
```js
export default {
@ -95,7 +95,7 @@ export default {
## Multiple Sidebars
You may show different sidebar depending on the page path. For example, as shown on this site, you might want to create a separate sections of content in your documentation like "Guide" page and "Config" page.
You can show different sidebars depending on the page path. For example, as shown on this site, you might want to create separate sections of content in your documentation for the "Guide" pages and "Config" pages.
To do so, first organize your pages into directories for each desired section:
@ -149,7 +149,7 @@ export default {
## Collapsible Sidebar Groups
By adding `collapsed` option to the sidebar group, it shows a toggle button to hide/show each section.
By adding the `collapsed` option to the sidebar group, it shows a toggle button to hide/show each section.
```js
export default {
@ -165,7 +165,7 @@ export default {
}
```
All sections are "open" by default. If you would like them to be "closed" on initial page load, set`collapsed` option to `true`.
All sections are open by default. If you want them to be closed by default instead, set the`collapsed` option to `true`.
If you would like to introduce your team, you may use Team components to construct the Team Page. There are two ways of using these components. One is to embed it in doc page, and another is to create a full Team Page.
If you would like to introduce your team, you can use Team components to construct the Team Page. There are two ways of using these components: to embed it in doc page, and to create a full Team page.
## Show team members in a page
You may use `<VPTeamMembers>` component exposed from `vitepress/theme` to display a list of team members on any page.
You can use the `<VPTeamMembers>` component exposed from `vitepress/theme` to display a list of team members on any page.
```html
<scriptsetup>
@ -56,21 +56,21 @@ Say hello to our awesome team.
<VPTeamMemberssize="small":members/>
```
The above will display a team member in card looking element. It should display something similar to below.
The above will display each team member in a card element, similar to this:
<VPTeamMemberssize="small":members/>
`<VPTeamMembers>` component comes in 2 different sizes, `small` and `medium`. While it boils down to your preference, usually `small` size should fit better when used in doc page. Also, you may add more properties to each member such as adding "description" or "sponsor" button. Learn more about it in [`<VPTeamMembers>`](#vpteammembers).
You can also add more properties to each member, such as a description or a sponsor button. Learn more about this in [`<VPTeamMembers>`](#vpteammembers).
Embedding team members in doc page is good for small size team where having dedicated full team page might be too much, or introducing partial members as a reference to documentation context.
The `<VPTeamMembers>` component comes in 2 different sizes, `small` and `medium`. While it's ultimately up to personal preference, the `small` size usually fits better when used in doc pages.
If you have large number of members, or simply would like to have more space to show team members, consider [creating a full team page](#create-a-full-team-page).
Embedding team members in a doc page is good for a small size team where having a dedicated full team page might be too much, or introducing partial members as a reference to documentation context. If you have large number of members, or simply want more space to show team members, consider [creating a full Team page](#create-a-full-team-page).
## Create a full Team Page
## Create a full Team page
Instead of adding team members to doc page, you may also create a full Team Page, similar to how you can create a custom [Home Page](./default-theme-home-page).
Instead of adding team members to doc page, you may also create a full Team page, similar to how you can create a custom [Home page](./default-theme-home-page).
To create a team page, first, create a new md file. The file name doesn't matter, but here lets call it `team.md`. In this file, set frontmatter option `layout: page`, and then you may compose your page structure using `TeamPage` components.
To create a team page, first create a new Markdown file. In this file, set the layout option in frontmatter to `page`, and use `TeamPage` components to compose your page structure.
```html
---
@ -111,17 +111,17 @@ const members = [
</VPTeamPage>
```
When creating a full team page, remember to wrap all components with `<VPTeamPage>` component. This component will ensure all nested team related components get the proper layout structure like spacings.
When creating a full team page, remember to wrap all components with the `<VPTeamPage>` component. This component will ensure all nested team related components get the proper layout structure and spacing.
`<VPPageTitle>` component adds the page title section. The title being `<h1>` heading. Use `#title` and `#lead` slot to document about your team.
The `<VPPageTitle>` component adds the page title section as an `<h1>` heading. Use the `#title` and `#lead` slots to provide information about your team.
`<VPMembers>` works as same as when used in a doc page. It will display list of members.
`<VPMembers>` works the same as when used in a doc page; it will simply display a list of members in cards.
### Add sections to divide team members
You may add "sections" to the team page. For example, you may have different types of team members such as Core Team Members and Community Partners. You can divide these members into sections to better explain the roles of each group.
You can add sections to the team page for separating team members into roles or categories. For example, you could have a Core Team Members section and a Community Partners section.
To do so, add `<VPTeamPageSection>` component to the `team.md` file we created previously.
To do this, add the`<VPTeamPageSection>` component to the Markdown file we created previously.
```html
---
@ -155,9 +155,9 @@ const partners = [...]
</VPTeamPage>
```
The `<VPTeamPageSection>` component can have `#title` and `#lead` slot similar to `VPTeamPageTitle` component, and also`#members` slot for displaying team members.
The `<VPTeamPageSection>` component has the `#title` and `#lead` slots from the `VPTeamPageTitle` component, and also a`#members` slot for displaying team members.
Remember to put in `<VPTeamMembers>` component within`#members` slot.
Remember to put a `<VPTeamMembers>` component within the`#members` slot.
## `<VPTeamMembers>`
@ -176,7 +176,7 @@ The `<VPTeamMembers>` component displays a given list of members.
```ts
interface Props {
// Size of each members. Defaults to `medium`.
// Size of each member. Defaults to `medium`.
size?: 'small' | 'medium'
// List of members to display.
@ -218,11 +218,11 @@ interface TeamMember {
## `<VPTeamPage>`
The root component when creating a full team page. It only accepts a single slot. It will style all passed in team related components.
The root component when creating a full team page. It only accepts a single slot. It will style all team related components passed in.
## `<VPTeamPageTitle>`
Adds "title" section of the page. Best use at the very beginning under `<VPTeamPage>`. It accepts `#title` and `#lead` slot.
Adds a "title" section to the page. Best used at the very beginning under `<VPTeamPage>`. It accepts `#title` and `#lead` slots.
```html
<VPTeamPage>
@ -240,7 +240,7 @@ Adds "title" section of the page. Best use at the very beginning under `<VPTeamP
## `<VPTeamPageSection>`
Creates a "section" within team page. It accepts `#title`, `#lead`, and `#members` slot. You may add as many sections as you like inside `<VPTeamPage>`.
Creates a section within the team page. It accepts `#title`, `#lead`, and `#members` slots. You can add as many sections as you like inside `<VPTeamPage>`.
Frontmatter enables page based configuration. In every markdown file, you can use frontmatter config to override site-level or theme-level config options. Also, there are config options which you can only define in frontmatter.
Frontmatter enables page based configuration. In every Markdown file, you can use frontmatter configu to override site-level or theme-level configuration options. There are also config options which are frontmatter-exclusive.
Example usage:
@ -62,7 +62,7 @@ description: VitePress
- Type: `HeadConfig[]`
Specify extra head tags to be injected for the current page. Will be appended after head tags injected by site-level config.
Specify extra head tags to be injected for the current page. Will be appended after the head tags injected by site-level config.
```yaml
---
@ -94,8 +94,8 @@ The following frontmatter options are only applicable when using the default the
Determines the layout of the page.
- `doc` - It applies default documentation styles to the markdown content.
- `home` - Special layout for "Home Page". You may add extra options such as `hero` and `features` to rapidly create beautiful landing page.
- `page` - Behave similar to `doc` but it applies no styles to the content. Useful when you want to create a fully custom page.
- `home` - Special layout for the home page. You can add extra options such as `hero` and `features` to create a beautiful landing page rapidly.
- `page` - Behaves similar to `doc`, but it applies no styles to the content. Useful when you want to create a fully custom page.
```yaml
---
@ -105,18 +105,18 @@ layout: doc
### hero <Badgetype="info"text="home page only"/>
Defines contents of home hero section when `layout` is set to `home`. More details in [Default Theme: Home Page](./default-theme-home-page).
Defines the contents of home hero section when the`layout` is set to `home`. More details in [Default Theme: Home Page](./default-theme-home-page).
### features <Badgetype="info"text="home page only"/>
Defines items to display in features section when `layout` is set to `home`. More details in [Default Theme: Home Page](./default-theme-home-page).
Defines the items to display in the features section when the`layout` is set to `home`. More details in [Default Theme: Home Page](./default-theme-home-page).
### navbar
- Type: `boolean`
- Default: `true`
Whether to display [navbar](./default-theme-nav).
Whether to display the [navbar](./default-theme-nav).
```yaml
---
@ -129,7 +129,7 @@ navbar: false
- Type: `boolean`
- Default: `true`
Whether to display [sidebar](./default-theme-sidebar).
Whether to display the [sidebar](./default-theme-sidebar).
```yaml
---
@ -137,6 +137,19 @@ sidebar: false
---
```
### footer
- Type: `boolean`
- Default: `true`
Whether to display the [footer](./default-theme-footer).
```yaml
---
footer: false
---
```
### aside
- Type: `boolean | 'left'`
@ -172,7 +185,7 @@ outline: [2, 4]
- Type: `boolean | Date`
- Default: `true`
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.
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
---
@ -185,7 +198,7 @@ lastUpdated: false
- Type: `boolean`
- Default: `true`
Whether to display [edit link](./default-theme-edit-link) in the footer of the current page.
Whether to display an [edit link](./default-theme-edit-link) in the footer of the current page.
```yaml
---
@ -193,24 +206,11 @@ editLink: false
---
```
### footer
- Type: `boolean`
- Default: `true`
Whether to display [footer](./default-theme-footer).
```yaml
---
footer: false
---
```
### pageClass
- Type: `string`
Add extra class name to a specific page.
Add extra CSS classes to a specific page.
```yaml
---
@ -218,7 +218,7 @@ pageClass: custom-page-class
---
```
Then you can customize styles of this specific page in `.vitepress/theme/custom.css` file:
You can then customize styles of that specific page in `.vitepress/theme/custom.css`:
VitePress offers several built-in APIs to let you access app data. VitePress also comes with a few built-in components that can be used globally.
The helper methods are globally importable from `vitepress` and are typically used in custom theme Vue components. However, they are also usable inside `.md` pages because markdown files are compiled into Vue [Single-File Components](https://vuejs.org/guide/scaling-up/sfc.html).
The helper methods are globally importable from `vitepress` and are typically used in custom Vue theme components. However, they are also usable inside `.md` pages because Markdown files are compiled into Vue [Single-File Components](https://vuejs.org/guide/scaling-up/sfc.html).
Methods that start with `use*` indicates that it is a [Vue 3 Composition API](https://vuejs.org/guide/introduction.html#composition-api) function ("Composable") that can only be used inside `setup()` or `<script setup>`.
Methods that start with `use*` indicates that it is a [Vue 3 Composition API](https://vuejs.org/guide/introduction.html#composition-api) composable function that can only be used inside `setup()` or `<script setup>`.
## `useData`<Badgetype="info"text="composable"/>
@ -139,9 +139,9 @@ The `<Content />` component displays the rendered markdown contents. Useful [whe
The `<ClientOnly />` component renders its slot only at client side.
Because VitePress applications are server-rendered in Node.js when generating static builds, any Vue usage must conform to the universal code requirements. In short, make sure to only access Browser / DOM APIs in beforeMount or mounted hooks.
Because VitePress applications are server-rendered in Node.js when generating static builds, any Vue usage must conform to the universal code requirements. In short, make sure to only access Browser and DOM APIs in the `beforeMount` or `mounted` hooks.
If you are using or demoing components that are not SSR-friendly (for example, contain custom directives), you can wrap them inside the `ClientOnly` component.
If you are using or demoing components that are not SSR-friendly (for example, contain custom directives), you can wrap them in the `ClientOnly` component.
Site config is where you can define the global settings of the site. App config options define settings that apply to every VitePress site, regardless of what theme it is using. For example, the base directory or the title of the site.
Site config is where you can define the global settings of the site. App config options define settings that apply to every VitePress site, regardless of what theme it is using, such as the base directory or the site title.
## Overview
@ -12,7 +12,7 @@ Site config is where you can define the global settings of the site. App config
The config file is always resolved from `<root>/.vitepress/config.[ext]`, where `<root>` 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:
It is recommended to use ES module syntax in config files. The config file should default export an object:
- Can be overridden per page via [frontmatter](./frontmatter-config#title)
Title for the site. When using the default theme, this will be displayed in the nav bar.
Title for the site. When using the default theme, this will be displayed in the navigation bar.
It will also be used as the default suffix for all individual page titles, unless [`titleTemplate`](#titletemplate) is defined. An individual page's final title will be the text content of its first `<h1>` header, combined with the global `title` as the suffix. For example with the following config and page content:
@ -527,13 +527,13 @@ export default {
}
```
Check the [type declaration and jsdocs](https://github.com/vuejs/vitepress/blob/main/src/node/markdown/markdown.ts) for all the options available.
Check the [type declarations and JSDoc](https://github.com/vuejs/vitepress/blob/main/src/node/markdown/markdown.ts) for all the options available.
### vite
- Type: `import('vite').UserConfig`
Pass raw [Vite Config](https://vitejs.dev/config/) to internal Vite dev server / bundler.
Pass raw [Vite config](https://vitejs.dev/config/) to internal Vite dev server / bundler.
`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.
`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.
Evorp
1 week ago
committed by
GitHub