From 54d982f2dc28576623f0edb220270abbb00fd9c9 Mon Sep 17 00:00:00 2001 From: Evan You Date: Tue, 7 Mar 2023 11:50:19 +0800 Subject: [PATCH] docs: more tweaks --- docs/guide/frontmatter.md | 2 +- docs/guide/getting-started.md | 13 +- docs/guide/what-is-vitepress.md | 6 + docs/reference/site-config.md | 287 +++++++++++++++----------------- 4 files changed, 148 insertions(+), 160 deletions(-) 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: