@ -18,7 +18,7 @@ Just want to try it out? Skip to the [Quickstart](./getting-started).
- **Blogs, Portfolios, and Marketing Sites**
VitePress supports [fully customized themes](./custom-theme), with the developer experience of a standard Vite + Vue application. Being built on Vite also means you can directly leverage Vite plugins from its rich ecosystem. In addition, VitePress provides flexible APIs to [load data](./data-loading) (local or remote) and [dynamically generate routes](./routing#dynamic-routes). You can use it to build almost anything as long as the data can be determined at build time.
VitePress supports [fully customized themes](./custom-theme), with the developer experience of a standard Vite + Vue application. Being built on Vite also means you can directly leverage Vite plugins from its rich ecosystem. Additionally, VitePress provides flexible APIs to [load data](./data-loading) (local or remote) and [dynamically generate routes](./routing#dynamic-routes). You can use it to build almost anything as long as the data can be determined at build time.
The official [Vue.js blog](https://blog.vuejs.org/) is a simple blog that generates its index page based on local content.
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.
Start a VitePress dev server using designated directory as root. Defaults to the current directory. The `dev` command can also be omitted when running in current directory.
### Usage
@ -64,7 +64,7 @@ vitepress preview [root]
## `vitepress init`
Start the [Setup Wizard](../guide/getting-started#setup-wizard) in current directory.
Start the [Setup Wizard](../guide/getting-started#setup-wizard) in the current directory.
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`, title in nav will be disabled. Useful when you have a `logo` that already contains the site title text.
```ts
export default {
@ -184,7 +184,7 @@ export type SidebarItem = {
- Default: `true`
- Can be overridden per page via [frontmatter](./frontmatter-config#aside)
Setting this value to `false` prevents rendering of aside container.\
Setting this value to `false` prevents rendering of the aside container.\
Setting this value to `true` renders the aside to the right.\
Setting this value to `left` renders the aside to the left.
@ -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 the outline container. Refer this interface for more details:
```ts
interface Outline {
@ -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.
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.
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.
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.
```js
export default {
@ -36,7 +36,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 will add the hyperlinked text "Edit this page" at the bottom of the doc page. You may customize this text by defining the `text` option.
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
export default {
@ -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:
The above configuration also supports HTML strings. For example, if you want to configure the footer text to have some links, you can adjust the configuration as follows:
```ts
export default {
@ -37,7 +37,7 @@ 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.
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.
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.
VitePress uses the brand color (`--vp-c-brand-1`) for the `name`. However, you may customize this color by overriding the `--vp-home-hero-name-color` variable.
```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 may also customize it further by combining it with`--vp-home-hero-name-background` to give the `name` a gradient color.
```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 features you would like to show right after the Hero section. To configure it, pass `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 theme when required.
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 last updated time of the content will be displayed in the lower right corner of the page. To enable it, add the `lastUpdated` option 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.
@ -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 theme-level will also enable the feature unless explicitly disabled at 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 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 a`doc` page.
```yaml
---
@ -10,9 +10,9 @@ 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.
Option `doc` is the default layout and it styles all the Markdown content into a "documentation" look. It works by wrapping all the content within the`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 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.
@ -23,15 +23,15 @@ It also provides documentation specific features listed below. These features ar
## 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 the same as in a`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 by 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, a sidebar will still show up if the page has a matching sidebar config.
## 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 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.
@ -4,7 +4,7 @@ The Nav is the navigation bar displayed on top of the page. It contains the site
## Site Title and Logo
By default, nav shows the title of the site referencing [`config.title`](./site-config#title) value. If you would like to change what's displayed on nav, you may define custom text in `themeConfig.siteTitle` option.
By default, nav shows the title of the site referencing the [`config.title`](./site-config#title) value. If you would like to change what's displayed on nav, you may define custom text in `themeConfig.siteTitle` option.
```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 logo if you want to add `alt` attribute or customize it based on dark/light mode. Refer to [`themeConfig.logo`](./default-theme-config#logo) for details.
## Navigation Links
You may define `themeConfig.nav` option to add links to your nav.
You may define the `themeConfig.nav` option to add links to your nav.
```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` 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 the `.md` suffix, and always start with `/`.
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 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 a`link` property since it becomes a button to open dropdown dialog.
You may further add "sections" to the dropdown menu items as well by passing in more nested items.
You may add further "sections" to the dropdown menu items as well by passing in more nested items.
```js
export default {
@ -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.
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 the `activeMatch` property and regex as a string value.
```js
export default {
@ -135,7 +135,7 @@ 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 regex string, but you must define it as a string. We can't use an actual RegExp object here because it isn't serializable during the build time.
:::
### Customize link's "target" and "rel" attributes
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 the 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.
## prev
@ -20,7 +20,7 @@ You can customize the text and link for the previous and next pages (shown at do
---
```
- To customize both text and link:
- To customize both the text and link:
```yaml
---
@ -30,7 +30,7 @@ You can customize the text and link for the previous and next pages (shown at do
[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.
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 actual file starting with `/`. If you add a trailing slash to the end of link, it will show the`index.md` of the corresponding directory.
```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 may further nest the sidebar items up to 6 level deep counting up from the root level. Note that nested items deeper than 6 levels gets ignored and will not be 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 may show different sidebars depending on the page path. For example, as shown on this site, you might want to create a separate section of content in your documentation like a "Guide" page and a "Config" page.
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 would like them to be "closed" on initial page load, 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 may use Team components to construct the Team Page. There are two ways of using these components. One is to embed it in a doc page, and another is 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 may use the `<VPTeamMembers>` component exposed from `vitepress/theme` to display a list of team members on any page.
```html
<scriptsetup>
@ -56,19 +56,19 @@ 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 a team member in a card looking element. It should display something similar to below.
<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).
`<VPTeamMembers>` component comes in 2 different sizes, `small` and `medium`. While it boils down to your preference, usually the `small` size should fit better when used in a doc page. Also, you may add more properties to each member such as adding a "description" or "sponsor" button. Learn more about it 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.
Embedding team members in doc page is good for 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 would like to have more space to show team members, consider [creating 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 a 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.
@ -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 `<VPTeamPage>` components. This component will ensure all nested team related components get the proper layout structure, like spacings.
`<VPPageTitle>` component adds the page title section. The title being `<h1>` heading. Use `#title` and `#lead` slot to document about your team.
`<VPPageTitle>` component adds the page title section. The title being an `<h1>` heading. Use `#title` and `#lead` slots to document your team.
`<VPMembers>` works as same as when used in a doc page. It will display list of members.
`<VPMembers>` works as same as when used in a doc page. It will display a list of members.
### 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.
To do so, add `<VPTeamPageSection>` component to the `team.md` file we created previously.
To do so, add a `<VPTeamPageSection>` component to the `team.md` 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 can have `#title` and `#lead` slots similar to the`VPTeamPageTitle` component, and also a`#members` slot for displaying team members.
Remember to put in `<VPTeamMembers>` component within`#members` slot.
Remember to put the `<VPTeamMembers>` component within the`#members` slot.
## `<VPTeamMembers>`
@ -222,7 +222,7 @@ The root component when creating a full team page. It only accepts a single slot
## `<VPTeamPageTitle>`
Adds "title" section of the page. Best use at the very beginning under `<VPTeamPage>`. It accepts `#title` and `#lead` slot.
Adds "title" section of 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 team page. It accepts `#title`, `#lead`, and `#members` slots. You may add as many sections as you like inside `<VPTeamPage>`.
The levels of header in the outline to display for the page. It's same as [config.themeConfig.outline.level](./default-theme-config#outline), and it overrides the value set in site-level config.
The levels of header in the outline to display for the page. It is the same as [config.themeConfig.outline.level](./default-theme-config#outline), and it overrides the value set in site-level config.
```yaml
---
@ -218,7 +218,7 @@ pageClass: custom-page-class
---
```
Then you can customize styles of this specific page in `.vitepress/theme/custom.css` file:
Then you can customize styles of this specific page in the `.vitepress/theme/custom.css` file:
@ -4,7 +4,7 @@ VitePress offers several built-in APIs to let you access app data. VitePress als
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).
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*` indicate 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>`.
Ruben Jing
4 weeks ago
committed by
GitHub