Custom Layout!
+ +
+ Custom 404 page!
+
+ Custom Layout!
+ +
+ Custom 404 page!
+
+
+ Custom home page!
+
+ Custom Layout!
+ +Custom Layout!
- - -{{ data }}
+```
+
+Output:
+
+```json
+{
+ "data": "hello"
+}
+```
+
+You'll notice the data loader itself does not export the `data`. It is VitePress calling the `load()` method behind the scenes and implicitly exposing the result via the `data` named export.
+
+This works even if the loader is async:
+
```js
export default {
async load() {
+ // fetch remote data
return (await fetch('...')).json()
}
}
```
-## Generating Data Based On Local Files
+## Data from Local Files
+
+When you need to generate data based on local files, you should use the `watch` option in the data loader so that changes made to these files can trigger hot updates.
+
+The `watch` option is also convenient in that you can use [glob patterns](https://github.com/mrmlnc/fast-glob#pattern-syntax) to match multiple files. The patterns can be relative to the loader file itself, and the `load()` function will receive the matched files as absolute paths:
```js
-import { readDirSync } from 'node:fs'
+import fs from 'node:fs'
+import parseFrontmatter from 'gray-matter'
export default {
- watch: ['*.md'],
- async load() {
- //
+ // watch all blog posts
+ watch: ['./posts/*.md'],
+ load(watchedFiles) {
+ // watchedFiles will be an array of absolute paths of the matched files.
+ // generate an array of blog post metadata that can be used to render
+ // a list in the theme layout
+ return watchedFiles.map(file => {
+ const content = fs.readFileSync(file, 'utf-8')
+ const { data, excerpt } = parseFrontmatter(content)
+ return {
+ file,
+ data,
+ excerpt
+ }
+ })
}
}
```
-## Typed Data
+## Typed Data Loaders
+
+When using TypeScript, you can type your loader and `data` export like so:
```ts
+import { defineLoader } from 'vitepress'
+
export interface Data {
// data type
}
@@ -41,9 +96,11 @@ export interface Data {
declare const data: Data
export { data }
-export default {
+export default defineLoader({
+ // type checked loader options
+ glob: ['...'],
async load(): Promise {
// ...
}
-}
+})
```
diff --git a/docs/guide/deploying.md b/docs/guide/deploy.md
similarity index 98%
rename from docs/guide/deploying.md
rename to docs/guide/deploy.md
index 4f5d76de548..904924c516f 100644
--- a/docs/guide/deploying.md
+++ b/docs/guide/deploy.md
@@ -1,4 +1,4 @@
-# Deploying
+# Deploy Your VitePress Site
The following guides are based on some shared assumptions:
@@ -17,7 +17,7 @@ The following guides are based on some shared assumptions:
::: tip
-If your site is to be served at a subdirectory (`https://example.com/subdir/`), then you have to set `'/subdir/'` as the [`base`](../config/app-config#base) in your `docs/.vitepress/config.js`.
+If your site is to be served at a subdirectory (`https://example.com/subdir/`), then you have to set `'/subdir/'` as the [`base`](/reference/site-config#base) in your `docs/.vitepress/config.js`.
**Example:** If you're using Github (or GitLab) Pages and deploying to `user.github.io/repo/`, then set your `base` to `/repo/`.
diff --git a/docs/guide/extending-default-theme.md b/docs/guide/extending-default-theme.md
new file mode 100644
index 00000000000..88647cecca6
--- /dev/null
+++ b/docs/guide/extending-default-theme.md
@@ -0,0 +1,138 @@
+# Extending the Default Theme
+
+VitePress' default theme is optimized for documentation, and can be customized. Consult the [Default Theme Config Overview](/reference/default-theme-config) for a comprehensive list of options.
+
+However, there are a number of cases where configuration alone won't be enough. For example:
+
+1. You need to tweak the CSS styling;
+2. You need to modify the Vue app instance, for example to register global components;
+3. You need to inject custom content into the theme via layout slots.
+
+These advanced customizations will require using a custom theme that "extends" the default theme.
+
+:::tip
+Before proceeding, make sure to first read [Using a Custom Theme](./custom-theme) to understand how custom themes work.
+:::
+
+## Customizing CSS
+
+The default theme CSS is customizable by overriding root level CSS variables:
+
+```js
+// .vitepress/theme/index.js
+import DefaultTheme from 'vitepress/theme'
+import './custom.css'
+
+export default DefaultTheme
+```
+
+```css
+/* .vitepress/theme/custom.css */
+:root {
+ --vp-c-brand: #646cff;
+ --vp-c-brand-light: #747bff;
+}
+```
+
+See [default theme CSS variables](https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css) that can be overridden.
+
+## Registering Global Components
+
+```js
+// .vitepress/theme/index.js
+import DefaultTheme from 'vitepress/theme'
+
+export default {
+ extends: DefaultTheme,
+ enhanceApp(ctx) {
+ // register your custom global components
+ ctx.app.component('MyGlobalComponent' /* ... */)
+ }
+}
+```
+
+Since we are using Vite, you can also leverage Vite's [glob import feature](https://vitejs.dev/guide/features.html#glob-import) to auto register a directory of components.
+
+## Layout Slots
+
+The default theme's `
+
+Just want to try it out? Skip to the [Quickstart](./getting-started).
+
+
+
+## Use Cases
+
+- **Documentation**
+
+ VitePress ships with a default theme designed for technical documentation, especially those that need to embed interactive demos. It powers this page you are reading right now, along with the documentation for [Vite](https://vitejs.dev/), [Pinia](https://pinia.vuejs.org/), [VueUse](https://vueuse.org/), [Mermaid](https://mermaid.js.org/), [Wikimedia Codex](https://doc.wikimedia.org/codex/latest/), and many more.
+
+ The [official Vue.js documentation](https://vuejs.org/) is also based on VitePress, but uses a custom theme shared between multiple translations.
+
+- **Blogs, Portfolios, and Marketing Sites**
+
+ VitePress supports [fully customized themes](/guide/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](/guide/data-loading) (local or remote) and [dynamically generate routes](/guide/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.
## Developer Experience
@@ -18,7 +38,7 @@ Unlike many traditional SSGs, a website generated by VitePress is in fact a [Sin
- **Fast Initial Load**
- The initial visit to any page will be served the static, pre-rendered HTML for maximum loading speed, together with a JavaScript bundle that turns the page into a Vue SPA ("hydration"). The hydration process is extremely fast: on [PageSpeed Insights](https://pagespeed.web.dev/), typical VitePress sites achieve near-perfect performance scores even on low-end mobile devices with a slow network.
+ The initial visit to any page will be served the static, pre-rendered HTML for blazing fast loading speed and optimal SEO. The page then loads a JavaScript bundle that turns the page into a Vue SPA ("hydration"). The hydration process is extremely fast: on [PageSpeed Insights](https://pagespeed.web.dev/report?url=https%3A%2F%2Fvitepress.vuejs.org%2F), typical VitePress sites achieve near-perfect performance scores even on low-end mobile devices with a slow network.
- **Fast Post-load Navigation**
@@ -28,14 +48,6 @@ Unlike many traditional SSGs, a website generated by VitePress is in fact a [Sin
To be able to hydrate the dynamic Vue parts embedded inside static Markdown, each Markdown page is processed as a Vue component and compiled into JavaScript. This may sound inefficient, but the Vue compiler is smart enough to separate the static and dynamic parts, minimizing both the hydration cost and payload size. For the initial page load, the static parts are automatically eliminated from the JavaScript payload and skipped during hydration.
-## Theming & Extensibility
-
-VitePress ships with a feature-rich default theme designed for documentation purposes. It allows you to spin up a beautiful documentation site like this one with minimal effort, and doesn't require any Vue-specific knowledge.
-
-VitePress also supports fully customized themes 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. This makes VitePress an ideal choice for building sites that is content-centric but also requires non-trivial interactivity. The [Vue.js documentation](https://github.com/vuejs/docs) is a good example of such customization.
-
-And of course, you can use it to build a blog! The [official Vue.js blog](https://github.com/vuejs/blog) is also built with VitePress.
-
## What About VuePress?
VitePress is the spiritual successor of VuePress. The original VuePress was based on Vue 2 and webpack. With Vue 3 and Vite under the hood, VitePress provides significantly better DX, better production performance, a more polished default theme, and a more flexible customization API.
diff --git a/docs/index.md b/docs/index.md
index e3e88564947..9d283151da6 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -7,7 +7,7 @@ titleTemplate: Vite & Vue Powered Static Site Generator
hero:
name: VitePress
text: Vite & Vue Powered Static Site Generator
- tagline: Simple, powerful, and performant. Meet the modern SSG framework you've always wanted.
+ tagline: Simple, powerful, and fast. Meet the modern SSG framework you've always wanted.
actions:
- theme: brand
text: Get Started
@@ -17,12 +17,22 @@ hero:
link: https://github.com/vuejs/vitepress
features:
- - title: "Vite: The DX that can't be beat"
- details: Feel the speed of Vite. Instant server start and lightning fast HMR that stays fast regardless of the app size.
- - title: Designed to be simplicity first
- details: With Markdown-centered content, it's built to help you focus on writing and deployed with minimum configuration.
- - title: Power of Vue meets Markdown
- details: Enhance your content with all the features of Vue in Markdown, while being able to customize your site with Vue.
- - title: Fully static yet still dynamic
- details: Go wild with true SSG + SPA architecture. Static on page load, but engage users with 100% interactivity from there.
+ - icon: 📝
+ title: Focus on Your Content
+ details: Effortlessly create beautiful documentation sites with just markdown.
+ - icon:
+ src: vite.svg
+ width: 10
+ height: 10
+ title: Enjoy the Vite DX
+ details: Instant server start, lightning fast hot updates, and leverage Vite ecosystem plugins.
+ - icon:
+ src: vue.svg
+ width: 10
+ height: 10
+ title: Customize with Vue
+ details: Use Vue syntax and components directly in markdown, or build custom themes with Vue components.
+ - icon: 🚀
+ title: Ship Fast Sites
+ details: Fast initial load with static HTML, fast post-load navigation with client-side routing.
---
diff --git a/docs/public/vite.svg b/docs/public/vite.svg
new file mode 100644
index 00000000000..de4aeddc12b
--- /dev/null
+++ b/docs/public/vite.svg
@@ -0,0 +1,15 @@
+
diff --git a/docs/public/vue.svg b/docs/public/vue.svg
new file mode 100644
index 00000000000..71c1cfb9afa
--- /dev/null
+++ b/docs/public/vue.svg
@@ -0,0 +1,4 @@
+
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
new file mode 100644
index 00000000000..0536d41e498
--- /dev/null
+++ b/docs/reference/cli.md
@@ -0,0 +1,74 @@
+# Command Line Interface
+
+## `vitepress dev`
+
+Start VitePress dev server using designated directory as root. Defaults to current directory. The `dev` command can also be omitted when running in current directory.
+
+### Usage
+
+```sh
+# start in current directory, omitting `dev`
+vitepress
+
+# start in sub directory
+vitepress dev [root]
+```
+
+### Options
+
+| Option | Description |
+| - | - |
+| `--open [path]` | Open browser on startup (`boolean \| string`) |
+| `--port