diff --git a/docs/guide/frontmatter.md b/docs/guide/frontmatter.md
index 54a7d978..8c3b04d5 100644
--- a/docs/guide/frontmatter.md
+++ b/docs/guide/frontmatter.md
@@ -9,7 +9,7 @@ editLink: true
---
```
-Many site or default theme config options have corresponding options in frontmatter. You can use frontmatter to override specific behavior for the current page only. For details, see [Frontmatter Config Reference](/reference/frontmatter-config),
+Many site or default theme config options have corresponding options in frontmatter. You can use frontmatter to override specific behavior for the current page only. For details, see [Frontmatter Config Reference](/reference/frontmatter-config).
You can also define custom frontmatter data of your own, to be used in dynamic Vue expressions on the page. Frontmatter data can be accessed via the special `$frontmatter` global variable:
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index 28ff8251..a96df314 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -1,12 +1,19 @@
# Getting Started
-## Prerequisites
+## Try It Online
-VitePress requires [Node.js](https://nodejs.org/) version 16 or higher.
+You can try VitePress directly in your browser on [StackBlitz](https://vitepress.new).
## Installation
-VitePress can be used on its own, or be installed into an existing project. Either way, you can install it with:
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) version 16 or higher.
+- Terminal for accessing VitePress via its command line interface (CLI).
+- Text Editor with [Markdown](https://en.wikipedia.org/wiki/Markdown) syntax support.
+ - [VSCode](https://code.visualstudio.com/) is recommended, along with the [official Vue extension](https://marketplace.visualstudio.com/items?itemName=Vue.volar).
+
+VitePress can be used on its own, or be installed into an existing project. In both cases, you can install it with:
::: code-group
diff --git a/docs/guide/what-is-vitepress.md b/docs/guide/what-is-vitepress.md
index 8b63caf6..ce6ea009 100644
--- a/docs/guide/what-is-vitepress.md
+++ b/docs/guide/what-is-vitepress.md
@@ -2,6 +2,12 @@
VitePress is a [Static Site Generator](https://en.wikipedia.org/wiki/Static_site_generator) (SSG). It is designed for building performant content-centric websites, such as this documentation you are reading right now. It also powers the documentation for [Vue.js](https://vuejs.org/), [Vite](https://vitejs.dev/), and many more. In a nutshell, VitePress takes your source content written in [Markdown](https://en.wikipedia.org/wiki/Markdown), applies a theme to it, and generates a directory of static HTML pages (and necessary asset files) that can be easily deployed anywhere.
+
+
+Just want to try it out? Skip to the [Quickstart](./getting-started).
+
+
+
## Developer Experience
VitePress aims to provide a great Developer Experience (DX) when working with Markdown content.
diff --git a/docs/reference/site-config.md b/docs/reference/site-config.md
index 33059adb..0ca377ea 100644
--- a/docs/reference/site-config.md
+++ b/docs/reference/site-config.md
@@ -24,21 +24,9 @@ Site config is where you can define the global settings of the site. App config
### Config Resolution
-Place your configuration file at `.vitepress/config.js`. This is where all VitePress-specific files will be placed.
-
-```
-.
-├─ docs
-│ ├─ .vitepress
-│ │ └─ config.js
-│ └─ index.md
-└─ package.json
-```
-
-::: tip
-You can also use any of `.ts`, `.cjs`, `.mjs`, `.cts`, `.mts` as the config file extension.
-:::
+The config file is always resolved from `/.vitepress/config.[ext]`, where `` is your VitePress [project root](/guide/routing#root-and-source-directory), and `[ext]` is one of the supported file extensions. TypeScript is supported out of the box. Supported extensions include `.js`, `.ts`, `.cjs`, `.mjs`, `.cts`, and `.mts`.
+It is recommended to use ES modules syntax in config files. The config file should default export an object:
```ts
export default {
@@ -52,20 +40,7 @@ export default {
### Config Intellisense
-Since VitePress ships with TypeScript typings, you can leverage your IDE's intellisense with jsdoc type hints:
-
-```js
-/**
- * @type {import('vitepress').UserConfig}
- */
-const config = {
- // ...
-}
-
-export default config
-```
-
-Alternatively, you can use the `defineConfig` helper at which should provide intellisense without the need for jsdoc annotations:
+Using the `defineConfig` helper will provide TypeScript-powered intellisense for config options. Assuming your IDE supports it, this should work in both JavaScript and TypeScript.
```js
import { defineConfig } from 'vitepress'
@@ -75,11 +50,9 @@ export default defineConfig({
})
```
-VitePress also directly supports TS config files. You can use `.vitepress/config.ts` with the `defineConfig` helper as well.
-
### Typed Theme Config
-By default, `defineConfig` helper leverages the theme config type from default theme:
+By default, `defineConfig` helper expects the theme config type from default theme:
```ts
import { defineConfig } from 'vitepress'
@@ -95,7 +68,7 @@ If you use a custom theme and want type checks for the theme config, you'll need
```ts
import { defineConfigWithTheme } from 'vitepress'
-import { ThemeConfig } from 'your-theme'
+import type { ThemeConfig } from 'your-theme'
export default defineConfigWithTheme({
themeConfig: {
@@ -110,42 +83,59 @@ export default defineConfigWithTheme({
- Type: `string`
- Default: `VitePress`
+- 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. This will be displayed in the nav bar. Also used as the suffix for all page titles unless `titleTemplate` is defined.
+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 `
` header, combined with the global `title` as the suffix. For example with the following config and page content:
```ts
export default {
- title: 'VitePress'
+ title: 'My Awesome Site'
}
```
+```md
+# Hello
+```
+
+The title of the page will be `Hello | My Awesome Site`.
### titleTemplate
- Type: `string | boolean`
+- Can be overridden per page via [frontmatter](./frontmatter-config#titletemplate)
-The suffix for the title. For example, if you set `title` as `VitePress` and set `titleTemplate` as `My Site`, the html title becomes `VitePress | My Site`.
-
-Set `false` to disable the feature. If the option is `undefined`, then the value of `title` option will be used.
+Allows customizing each page's title suffix or the entire title. For example:
```ts
export default {
- title: 'VitePress',
- titleTemplate: 'Vite & Vue powered static site generator'
+ title: 'My Awesome Site',
+ titleTemplate: 'Custom Suffix'
}
```
+```md
+# Hello
+```
+
+The title of the page will be `Hello | Custom Suffix`.
-To configure a title separator other than `|`, you can omit `title` and use the `:title` symbol in `titleTemplate`.
+To completely customize how the title should be rendered, you can use the `:title` symbol in `titleTemplate`:
```ts
export default {
- titleTemplate: ':title - Vitepress'
+ titleTemplate: ':title - Custom Suffix'
}
```
+Here `:title` will be replaced with the text inferred from the page's first `
` header. The title of the previous example page will be `Hello - Custom Suffix`.
+
+The option can be set to `false` to disable title suffixes.
+
### description
- Type: `string`
- Default: `A VitePress site`
+- Can be overridden per page via [frontmatter](./frontmatter-config#description)
Description for the site. This will render as a `` tag in the page HTML.
@@ -155,21 +145,32 @@ export default {
}
```
-### base
-
-- Type: `string`
-- Default: `/`
+### head
-The base URL the site will be deployed at. You will need to set this if you plan to deploy your site under a sub path, for example, GitHub pages. If you plan to deploy your site to `https://foo.github.io/bar/`, then you should set base to `'/bar/'`. It should always start and end with a slash.
+- Type: `HeadConfig[]`
+- Default: `[]`
+- Can be appended per page via [frontmatter](./frontmatter-config#head)
-The base is automatically prepended to all the URLs that start with / in other options, so you only need to specify it once.
+Additional elements to render in the `` tag in the page HTML. The user-added tags are rendered before the closing `head` tag, after VitePress tags.
```ts
export default {
- base: '/base/'
+ head: [
+ [
+ 'link',
+ { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }
+ ]
+ // would render:
+ ]
}
```
+```ts
+type HeadConfig =
+ | [string, Record]
+ | [string, Record, string]
+```
+
### lang
- Type: `string`
@@ -183,31 +184,21 @@ export default {
}
```
-### head
+### base
-- Type: `HeadConfig[]`
-- Default: `[]`
+- Type: `string`
+- Default: `/`
-Additional elements to render in the `` tag in the page HTML. The user-added tags are rendered before the closing `head` tag, after VitePress tags.
+The base URL the site will be deployed at. You will need to set this if you plan to deploy your site under a sub path, for example, GitHub pages. If you plan to deploy your site to `https://foo.github.io/bar/`, then you should set base to `'/bar/'`. It should always start and end with a slash.
+
+The base is automatically prepended to all the URLs that start with / in other options, so you only need to specify it once.
```ts
export default {
- head: [
- [
- 'link',
- { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }
- ]
- // would render:
- ]
+ base: '/base/'
}
```
-```ts
-type HeadConfig =
- | [string, Record]
- | [string, Record, string]
-```
-
## Routing
### cleanUrls
@@ -215,23 +206,17 @@ type HeadConfig =
- Type: `boolean`
- Default: `false`
-Allows removing trailing `.html` from URLs.
+When set to `true`, VitePress will remove the trailing `.html` from URLs. Also see [Generating Clean URL](/guide/routing#generating-clean-url).
-```ts
-export default {
- cleanUrls: true
-}
-```
-
-::: warning
-Enabling this may require additional configuration on your hosting platform. For it to work, your server must serve `/foo.html` on requesting `/foo` **without a redirect**.
+::: warning Server Support Required
+Enabling this may require additional configuration on your hosting platform. For it to work, your server must be able to serve `/foo.html` when visiting `/foo` **without a redirect**.
:::
### rewrites
- Type: `Record`
-Defines custom directory <-> URL mappings. See [Routing: Customize the Mappings](/guide/routing#customize-the-mappings) for more details.
+Defines custom directory <-> URL mappings. See [Routing: Route Rewrites](/guide/routing#route-rewrites) for more details.
```ts
export default {
@@ -241,40 +226,97 @@ export default {
}
```
-## Theming
+## Build
-### appearance
+### srcDir
-- Type: `boolean | 'dark'`
-- Default: `true`
+- Type: `string`
+- Default: `.`
-Whether to enable dark mode or not.
+The directory where your markdown pages are stored, relative to project root. Also see [Root and Source Directory](/guide/routing#root-and-source-directory).
-- If the option is set to `true`, the default theme will be determined by the user's preferred color scheme.
-- If the option is set to `dark`, the theme will be dark by default, unless the user manually toggles it.
-- If the option is set to `false`, users will not be able to toggle the theme.
+```ts
+export default {
+ srcDir: './src'
+}
+```
+
+### srcExclude
-It also injects inline script that tries to read users settings from local storage by `vitepress-theme-appearance` key and restores users preferred color mode.
+- Type: `string`
+- Default: `undefined`
+
+A [glob pattern](https://github.com/mrmlnc/fast-glob#pattern-syntax) for matching markdown files that should be excluded as source content.
```ts
export default {
- appearance: true
+ srcExclude: ['**/README.md', '**/TODO.md']
}
```
-### lastUpdated
+### outDir
-- Type: `boolean`
+- Type: `string`
+- Default: `./.vitepress/dist`
+
+The build output location for the site, relative to [project root](/guide/routing#root-and-source-directory).
+
+```ts
+export default {
+ outDir: '../public'
+}
+```
+
+### cacheDir
+
+- Type: `string`
+- Default: `./.vitepress/cache`
+
+The directory for cache files, relative to [project root](/guide/routing#root-and-source-directory). See also: [cacheDir](https://vitejs.dev/config/shared-options.html#cachedir).
+
+```ts
+export default {
+ cacheDir: './.vitepress/.vite'
+}
+```
+
+### ignoreDeadLinks
+
+- Type: `boolean | 'localhostLinks'`
- Default: `false`
-Use git commit to get the timestamp. This option enables the default theme to display the page's last updated time. You can customize the text via [`themeConfig.lastUpdatedText`](./default-theme-config#lastupdatedtext) option.
+When set to `true`, VitePress will not fail builds due to dead links. When set to `'localhostLinks'`, the build will fail on dead links, but won't check `localhost` links.
```ts
export default {
- lastUpdated: true
+ ignoreDeadLinks: true
}
```
+## Theming
+
+### appearance
+
+- Type: `boolean | 'dark'`
+- Default: `true`
+
+Whether to enable dark mode (by adding the `.dark` class to the `` element).
+
+- If the option is set to `true`, the default theme will be determined by the user's preferred color scheme.
+- If the option is set to `dark`, the theme will be dark by default, unless the user manually toggles it.
+- If the option is set to `false`, users will not be able to toggle the theme.
+
+This option injects an inline script that restores users settings from local storage using the `vitepress-theme-appearance` key. This ensures the `.dark` class is applied before the page is rendered to avoid flickering.
+
+### lastUpdated
+
+- Type: `boolean`
+- Default: `false`
+
+Whether to get the last updated timestamp for each page using Git. The timestamp will be included in each page's page data, accessible via [`useData`](/reference/runtime-api#usedata).
+
+When using the default theme, enabling this option will display each page's last updated time. You can customize the text via [`themeConfig.lastUpdatedText`](./default-theme-config#lastupdatedtext) option.
+
## Customization
### markdown
@@ -361,73 +403,6 @@ Pass raw [Vite Config](https://vitejs.dev/config/) to internal Vite dev server /
Pass raw [`@vitejs/plugin-vue` options](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue#options) to the internal plugin instance.
-## Build
-
-### srcDir
-
-- Type: `string`
-- Default: `.`
-
-The directory where your markdown pages are stored, relative to project root.
-
-```ts
-export default {
- srcDir: './src'
-}
-```
-
-### srcExclude
-
-- Type: `string`
-- Default: `undefined`
-
-A [glob pattern](https://github.com/mrmlnc/fast-glob#pattern-syntax) for matching markdown files that should be excluded as source content.
-
-```ts
-export default {
- srcExclude: ['**/README.md', '**/TODO.md']
-}
-```
-
-### outDir
-
-- Type: `string`
-- Default: `./.vitepress/dist`
-
-The build output location for the site, relative to project root (`docs` folder if you're running `vitepress build docs`).
-
-```ts
-export default {
- outDir: '../public'
-}
-```
-
-### cacheDir
-
-- Type: `string`
-- Default: `./.vitepress/cache`
-
-The directory for cache files, relative to project root (`docs` folder if you're running `vitepress build docs`). See also: [cacheDir](https://vitejs.dev/config/shared-options.html#cachedir).
-
-```ts
-export default {
- cacheDir: './.vitepress/.vite'
-}
-```
-
-### ignoreDeadLinks
-
-- Type: `boolean | 'localhostLinks'`
-- Default: `false`
-
-When set to `true`, VitePress will not fail builds due to dead links. When set to `localhostLinks`, the build will fail on dead links, but won't check `localhost` links.
-
-```ts
-export default {
- ignoreDeadLinks: true
-}
-```
-
## Build Hooks
VitePress build hooks allow you to add new functionality and behaviors to your website: