diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
deleted file mode 100644
index 4cd9cd30..00000000
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ /dev/null
@@ -1,32 +0,0 @@
----
-name: Bug report
-about: Create a report to help us improve
-title: ''
-labels: 'bug: pending triage'
-assignees: ''
-
----
-
-
-
-**Describe the bug**
-A clear and concise description of what the bug is.
-
-**To Reproduce**
-Steps to reproduce the behavior:
-
-**Expected behavior**
-A clear and concise description of what you expected to happen.
-
-**System Info**
-- vitepress version:
-- vite version:
-- Node version:
-- OS version:
-
-**Additional context**
-Add any other context about the problem here.
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 00000000..ba88135e
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,60 @@
+name: "\U0001F41E Bug report"
+description: Create a report to help us improve
+labels: ["bug: pending triage"]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ "Thanks for taking the time to fill out this bug report!
+ VitePress is still WIP, and it is not compatible with VuePress.
+ Please do not open issue about default theme missing features or something doesn't work like VuePress."
+ - type: textarea
+ id: bug-description
+ attributes:
+ label: Describe the bug
+ description: A clear and concise description of what the bug is. If you intend to submit a PR for this issue, tell us in the description. Thanks!
+ placeholder: Bug description
+ validations:
+ required: true
+ - type: textarea
+ id: reproduction
+ attributes:
+ label: Reproduction
+ description: Steps to reproduce the behavior
+ placeholder: Reproduction
+ validations:
+ required: true
+ - type: textarea
+ id: expected
+ attributes:
+ label: Expected behavior
+ description: A clear and concise description of what you expected to happen.
+ placeholder: Expected behavior
+ validations:
+ required: true
+ - type: textarea
+ id: system-info
+ attributes:
+ label: System Info
+ description: Output of `npx envinfo --system --npmPackages vitepress --binaries --browsers`
+ render: shell
+ placeholder: System, Binaries, Browsers
+ validations:
+ required: true
+ - type: textarea
+ id: additional-context
+ attributes:
+ label: Additional context
+ description: Add any other context or screenshots about the feature request here.
+ - type: checkboxes
+ id: checkboxes
+ attributes:
+ label: Validations
+ description: Before submitting the issue, please make sure you do the following
+ options:
+ - label: Follow our [Code of Conduct](https://vuejs.org/coc)
+ required: true
+ - label: Read the [docs](https://vitepress.vuejs.org/).
+ required: true
+ - label: Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
+ required: true
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
deleted file mode 100644
index bbcbbe7d..00000000
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ /dev/null
@@ -1,20 +0,0 @@
----
-name: Feature request
-about: Suggest an idea for this project
-title: ''
-labels: ''
-assignees: ''
-
----
-
-**Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
-
-**Describe the solution you'd like**
-A clear and concise description of what you want to happen.
-
-**Describe alternatives you've considered**
-A clear and concise description of any alternative solutions or features you've considered.
-
-**Additional context**
-Add any other context or screenshots about the feature request here.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 00000000..78e74d53
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,45 @@
+name: "\U0001F680 New feature proposal"
+description: Suggest an idea for this project
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Thanks for your interest in the project and taking the time to fill out this feature report!
+ - type: textarea
+ id: feature-description
+ attributes:
+ label: Is your feature request related to a problem? Please describe.
+ description: "A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]"
+ validations:
+ required: true
+ - type: textarea
+ id: suggested-solution
+ attributes:
+ label: Describe the solution you'd like
+ description: A clear and concise description of what you want to happen.
+ validations:
+ required: true
+ - type: textarea
+ id: alternative
+ attributes:
+ label: Describe alternatives you've considered
+ description: A clear and concise description of any alternative solutions or features you've considered.
+ - type: textarea
+ id: additional-context
+ attributes:
+ label: Additional context
+ description: Add any other context or screenshots about the feature request here.
+ - type: checkboxes
+ id: checkboxes
+ attributes:
+ label: Validations
+ description: Before submitting the issue, please make sure you do the following
+ options:
+ - label: Follow our [Code of Conduct](https://vuejs.org/coc)
+ required: true
+ - label: Read the [docs](https://vitepress.vuejs.org/).
+ required: true
+ - label: Read the [Contributing Guidelines](https://github.com/vuejs/vitepress/blob/master/.github/contributing.md).
+ required: true
+ - label: Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
+ required: true
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 488ab91f..43b3309e 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -7,14 +7,27 @@ jobs:
runs-on: ubuntu-latest
strategy:
matrix:
- node-version: [14, 15]
+ node-version: [14, 16]
steps:
- - uses: actions/checkout@v1
- - name: Use Node.js ${{ matrix.node-version }}
- uses: actions/setup-node@v1
+ - name: Checkout
+ uses: actions/checkout@v2
+
+ - name: Install pnpm
+ uses: pnpm/action-setup@v2.0.1
+ with:
+ version: 6.15.1
+
+ - name: Set node version to ${{ matrix.node_version }}
+ uses: actions/setup-node@v2
with:
- node-version: ${{ matrix.node-version }}
- - name: install and test
- run: |
- yarn install
- yarn test
+ node-version: ${{ matrix.node_version }}
+ cache: "pnpm"
+
+ - name: Install deps
+ run: pnpm install
+
+ - name: Build
+ run: pnpm run build
+
+ - name: Test
+ run: pnpm run test
diff --git a/.gitignore b/.gitignore
index 7726c297..0e9bd5c8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,6 @@
/coverage
-/src/client/shared
-/src/node/shared
+/src/client/shared.ts
+/src/node/shared.ts
*.log
.DS_Store
.vite_opt_cache
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5b3cca34..18cd84d7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,217 @@
+## [0.19.2](https://github.com/vuejs/vitepress/compare/v0.19.1...v0.19.2) (2021-09-28)
+
+### Bug Fixes
+
+- encode urls that conflict w/ vite built-in replacements ([3940625](https://github.com/vuejs/vitepress/commit/3940625121455b7ad6e5ea8ebb3e1cf2faf9c7fc))
+
+## [0.19.1](https://github.com/vuejs/vitepress/compare/v0.19.0...v0.19.1) (2021-09-21)
+
+- Fix build
+
+# [0.19.0](https://github.com/vuejs/vitepress/compare/v0.18.1...v0.19.0) (2021-09-21)
+
+### Features
+
+- upgrade vue, simplify deps ([9030486](https://github.com/vuejs/vitepress/commit/9030486409f10a59115d874b9365f71348ed76c2))
+- use `markdown-it-attrs` for markdown-it plugins ([#393](https://github.com/vuejs/vitepress/issues/393)) ([610e9b7](https://github.com/vuejs/vitepress/commit/610e9b7111462d3aace878017fa4d359cd2ae7ea))
+
+## [0.18.1](https://github.com/vuejs/vitepress/compare/v0.18.0...v0.18.1) (2021-09-16)
+
+### Bug Fixes
+
+- ensure stable pages entry order across builds ([929bcf5](https://github.com/vuejs/vitepress/commit/929bcf50ee634d9fe73adbe2aae5f7038b048e5a))
+
+# [0.18.0](https://github.com/vuejs/vitepress/compare/v0.17.3...v0.18.0) (2021-09-14)
+
+### Features
+
+- map mode + remove deprecated options ([b94b163](https://github.com/vuejs/vitepress/commit/b94b163a3a931fe03e69547391d6ac22eb41b789))
+- support `
+
+
+ {{ theme.heroText }}
+
+```
+
+### `useRoute`
+
+Returns the current route object with the following type:
+
+```ts
+interface Route {
+ path: string
+ data: PageData
+ component: Component | null
+}
+```
+
+### `useRouter`
+
+Returns the VitePress router instance so you can programmatically navigate to another page.
+
+```ts
+interface Router {
+ route: Route
+ go: (href?: string) => Promise
+}
+```
+
+### `withBase`
+
+- **Type**: `(path: string) => string`
+
+ Appends the configured [`base`](/config/basics.html#base) to a given URL path. Also see [Base URL](/guide/assets.html#base-url).
+
+## Global Components
+
+VitePress comes with few built-in component that can be used globally. You may use these components in your markdown or your custom theme configuration.
+
+### ``
+
+The `` component displays the rendered markdown contents. Useful [when creating your own theme](https://vitepress.vuejs.org/guide/customization.html).
+
+```vue
+
+ Custom Layout!
+
+
+```
+
+### ``
+
+The `` 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.
+
+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.
+
+```html
+
+
+
+```
diff --git a/docs/guide/assets.md b/docs/guide/assets.md
index acbbe57d..9b2a5992 100644
--- a/docs/guide/assets.md
+++ b/docs/guide/assets.md
@@ -26,10 +26,30 @@ Note that you should reference files placed in `public` using root absolute path
If your site is deployed to a non-root URL, you will need to set the `base` option in `.vitepress/config.js`. For example, if you plan to deploy your site to `https://foo.github.io/bar/`, then `base` should be set to `'/bar/'` (it should always start and end with a slash).
-With a base URL, to reference an image in `public`, you'd have to use URLs like `/bar/image.png`. But this is brittle if you ever decide to change the base. To help with that, VitePress provides a built-in helper `$withBase` (injected onto Vue's prototype) that generates the correct path:
+All your static asset paths are automatically processed to adjust for different `base` config values. For example, if you have an absolute reference to an asset under `public` in your markdown:
-```html
-
+```md
+
+```
+
+You do **not** need to update it when you change the `base` config value in this case.
+
+However, if you are authoring a theme component that links to assets dynamically, e.g. an image whose `src` is based on a theme config value:
+
+```vue
+
```
-Note you can use the above syntax not only in theme components, but in your Markdown files as well.
+In this case it is recommended to wrap the path with the [`withBase` helper](/guide/api.html#withbase) provided by VitePress:
+
+```vue
+
+
+
+
+
+```
diff --git a/docs/guide/customization.md b/docs/guide/customization.md
deleted file mode 100644
index 10cf4e0d..00000000
--- a/docs/guide/customization.md
+++ /dev/null
@@ -1,51 +0,0 @@
-# Customization
-
-You can develop your custom theme by adding the `.vitepress/theme/index.js` file.
-
-```bash
-.
-├─ docs
-│ ├─ .vitepress
-│ │ ├─ theme
-│ │ │ └─ index.js
-│ │ └─ config.js
-│ └─ index.md
-└─ package.json
-```
-
-In `.vitepress/theme/index.js`, you must export theme object and register your own theme layout. Let's say you have your own `Layout` component like this.
-
-```vue
-
-
- Custom Layout!
-
-
-```
-
-Then include it in `.vitepress/theme/index.js`.
-
-```js
-// .vitepress/theme/index.js
-import Layout from './Layout.vue'
-
-export default {
- Layout,
- NotFound: () => 'custom 404', // <- this is a Vue 3 functional component
- enhanceApp({ app, router, siteData }) {
- // app is the Vue 3 app instance from `createApp()`. router is VitePress'
- // custom router. `siteData`` is a `ref`` of current site-level metadata.
- }
-}
-```
-
-If you want to extend the default theme, you can import it from `vitepress/theme`.
-
-```js
-// .vitepress/theme/index.js
-import DefaultTheme from 'vitepress/theme'
-
-export default {
- ...DefaultTheme
-}
-```
diff --git a/docs/guide/deploy.md b/docs/guide/deploy.md
index 423228b0..4221893c 100644
--- a/docs/guide/deploy.md
+++ b/docs/guide/deploy.md
@@ -1,3 +1,7 @@
+---
+sidebarDepth: 3
+---
+
# Deploying
The following guides are based on some shared assumptions:
@@ -198,7 +202,7 @@ pages:
3. Deploy to surge by typing `surge docs/.vitepress/dist`.
-You can also deploy to a [custom domain](http://surge.sh/help/adding-a-custom-domain) by adding `surge docs/.vitepress/dist yourdomain.com`.
+You can also deploy to a [custom domain](https://surge.sh/help/adding-a-custom-domain) by adding `surge docs/.vitepress/dist yourdomain.com`.
## Heroku
diff --git a/docs/guide/differences-from-vuepress.md b/docs/guide/differences-from-vuepress.md
index 94fdd4c0..eefa0c1e 100644
--- a/docs/guide/differences-from-vuepress.md
+++ b/docs/guide/differences-from-vuepress.md
@@ -1,3 +1,6 @@
+---
+sidebarDepth: 2
+---
# Differences from VuePress
VitePress and VuePress have different [design goals](../index.md). Both projects share similar config naming conventions. VitePress aims to have the bare minimum features needed for authoring docs. Other features are pushed to Themes. On the other hand, VuePress has more features out-of-the-box or enabled by its ecosystem of plugins.
@@ -22,8 +25,8 @@ In case you decide to move your project to VitePress, this is a list of differen
- Components in `.vitepress/components` [are not auto registered as global components](https://vuepress.vuejs.org/)
- Differences
- [Public files](https://vuepress.vuejs.org/guide/assets.html#public-files) that are directly copied to dist root moved from `.vitepress/public/` is `public/`
- - [styling](https://vuepress.vuejs.org/config/#styling) `.vitepress/styles/index.styl` and `.vitepress/styles/palette.styl` is `.vitepress/style.styl`
- - [App Level Enhancements](https://vuepress.vuejs.org/guide/basic-config.html#app-level-enhancements) API, app enhancements `.vitepress/enhanceApp.js` is `.vitepress/theme/index.js`.
+ - [styling](https://vuepress.vuejs.org/config/#styling) `.vitepress/styles/index.styl` and `.vitepress/styles/palette.styl` is not supported. See [Customizing CSS](/guide/theming.html#customizing-css).
+ - [App Level Enhancements](https://vuepress.vuejs.org/guide/basic-config.html#app-level-enhancements) API, app enhancements `.vitepress/enhanceApp.js` is now done in `.vitepress/theme/index.js`. See [Extending the Default Theme](/guide/theming.html#extending-the-default-theme).
## Markdown
@@ -31,7 +34,6 @@ In case you decide to move your project to VitePress, this is a list of differen
- Support for [toml in frontmatter](https://vuepress.vuejs.org/guide/frontmatter.html#alternative-frontmatter-formats)
- [details block](https://vuepress.vuejs.org/guide/markdown.html#custom-containers)
- [markdown slots](https://vuepress.vuejs.org/guide/markdown-slot.html)
- guide/using-vue.html#using-components).
- `~` prefix to explicitly specify a url is a [webpack module request](https://vuepress.vuejs.org/guide/assets.html#relative-urls)
## Site Config
@@ -67,7 +69,7 @@ In case you decide to move your project to VitePress, this is a list of differen
- `algolia` is `search.algolia`
- `searchPlaceholder` is `search.placeholder`
-# Default Theme
+## Default Theme
- Missing
- [`` and ``](https://vuepress.vuejs.org/theme/default-theme-config.html#code-groups-and-code-blocks)
diff --git a/docs/guide/frontmatter.md b/docs/guide/frontmatter.md
index a62c2b2c..3e18009f 100644
--- a/docs/guide/frontmatter.md
+++ b/docs/guide/frontmatter.md
@@ -9,7 +9,7 @@ editLink: true
---
```
-Between the triple-dashed lines, you can set [predefined variables](#predefined-variables), or even create custom ones of your own. These variables can be used via the $frontmatter
variable.
+Between the triple-dashed lines, you can set [predefined variables](#predefined-variables), or even create custom ones of your own. These variables can be used via the special $frontmatter
variable.
Here’s an example of how you could use it in your Markdown file:
diff --git a/docs/guide/global-computed.md b/docs/guide/global-computed.md
deleted file mode 100644
index ea46cf4f..00000000
--- a/docs/guide/global-computed.md
+++ /dev/null
@@ -1,89 +0,0 @@
-# Global Computed
-
-In VitePress, some core [computed properties](https://v3.vuejs.org/guide/computed.html#computed-properties) can be used by the default theme or custom themes. Or directly in Markdown pages using vue, for example using `$frontmatter.title` to access the title defined in the frontmatter section of the page.
-
-## $site
-
-This is the `$site` value of the site you're currently reading:
-
-```js
-{
- base: '/',
- lang: 'en-US',
- title: 'VitePress',
- description: 'Vite & Vue powered static site generator.',
- head: [],
- locales: {},
- themeConfig: $themeConfig
-}
-```
-
-## $themeConfig
-
-Refers to `$site.themeConfig`.
-
-```js
-{
- locales: {},
- repo: 'vuejs/vitepress',
- docsDir: 'docs',
- editLinks: true,
- editLinkText: 'Edit this page on GitHub',
- lastUpdated: 'Last Updated',
- nav: [...],
- sidebar: { ... }
-}
-```
-
-## $page
-
-This is the `$page` value of the page you're currently reading:
-
-```js
-{
- relativePath: 'guide/global-computed.md',
- title: 'Global Computed',
- headers: [
- { level: 2, title: '$site', slug: 'site' },
- { level: 2, title: '$page', slug: '$page' },
- ...
- ],
- frontmatter: $frontmatter,
- lastUpdated: 1606297645000
-}
-```
-
-## $frontmatter
-
-Reference of `$page.frontmatter`.
-
-```js
-{
- title: 'Docs with VitePress',
- editLink: true
-}
-```
-
-## $lang
-
-The language of the current page. Default: `en-US`.
-
-## $localePath
-
-The locale path prefix for the current page. Default: `/`.
-
-## $title
-
-Value of the `` label used for the current page.
-
-## $description
-
-The content value of the `` for the current page.
-
-## $withBase
-
-Helper method to generate correct path by prepending the `base` path configured in `.vitepress/config.js`. It's useful when you want to link to [public files with base path](./assets#public-files).
-
-```html
-
-```
diff --git a/docs/guide/markdown.md b/docs/guide/markdown.md
index fbbaf65f..e0efc2f0 100644
--- a/docs/guide/markdown.md
+++ b/docs/guide/markdown.md
@@ -1,3 +1,7 @@
+---
+sidebarDepth: 3
+---
+
# Markdown Extensions
## Header Anchors
@@ -28,9 +32,9 @@ For example, given the following directory structure:
And providing you are in `foo/one.md`:
```md
-[Home](/)
+[Home](/)
[foo](/foo/)
-[foo heading](./#heading)
+[foo heading](./#heading)
[bar - three](../bar/three)
[bar - three](../bar/three.md)
[bar - four](../bar/four.html)
@@ -56,7 +60,6 @@ Outbound links automatically get `target="_blank" rel="noopener noreferrer"`:
title: Blogging Like a Hacker
lang: en-US
---
-
```
This data will be available to the rest of the page, along with all custom and theming components.
@@ -124,6 +127,10 @@ Custom containers can be defined by their types, titles, and contents.
This is a tip
:::
+::: info
+This is an info box
+:::
+
::: warning
This is a warning
:::
@@ -139,6 +146,10 @@ This is a dangerous warning
This is a tip
:::
+::: info
+This is an info box
+:::
+
::: warning
This is a warning
:::
@@ -360,7 +371,7 @@ It also supports [line highlighting](#line-highlighting-in-code-blocks):
::: tip
-The value of `@` corresponds to `process.cwd()`.
+The value of `@` corresponds to the source root. By default it's the VitePress project root, unless `srcDir` is configured.
:::
You can also use a [VS Code region](https://code.visualstudio.com/docs/editor/codebasics#_folding) to only include the corresponding part of the code file. You can provide a custom region name after a `#` following the filepath (`snippet` by default):
@@ -392,12 +403,17 @@ You can also use a [VS Code region](https://code.visualstudio.com/docs/editor/co
VitePress uses [markdown-it](https://github.com/markdown-it/markdown-it) as the Markdown renderer. A lot of the extensions above are implemented via custom plugins. You can further customize the `markdown-it` instance using the `markdown` option in `.vitepress/config.js`:
```js
+const anchor = require('markdown-it-anchor')
+
module.exports = {
markdown: {
// options for markdown-it-anchor
- anchor: { permalink: false },
+ // https://github.com/valeriangalliat/markdown-it-anchor#permalinks
+ anchor: {
+ permalink: anchor.permalink.headerLink()
+ },
- // options for markdown-it-toc
+ // options for markdown-it-table-of-contents
toc: { includeLevel: [1, 2] },
config: (md) => {
diff --git a/docs/guide/theming.md b/docs/guide/theming.md
new file mode 100644
index 00000000..5797f843
--- /dev/null
+++ b/docs/guide/theming.md
@@ -0,0 +1,157 @@
+# Theming
+
+## Using a Custom Theme
+
+You can enable a custom theme by adding the `.vitepress/theme/index.js` file (the "theme entry file").
+
+```bash
+.
+├─ docs
+│ ├─ .vitepress
+│ │ ├─ theme
+│ │ │ └─ index.js
+│ │ └─ config.js
+│ └─ index.md
+└─ package.json
+```
+
+A VitePress custom theme is simply an object containing three properties and is defined as follows:
+
+```ts
+interface Theme {
+ Layout: Component // Vue 3 component
+ NotFound?: Component
+ enhanceApp?: (ctx: EnhanceAppContext) => void
+}
+
+interface EnhanceAppContext {
+ app: App // Vue 3 app instance
+ router: Router // VitePress router instance
+ siteData: Ref
+}
+```
+
+The theme entry file should export the theme as its default export:
+
+```js
+// .vitepress/theme/index.js
+import Layout from './Layout.vue'
+
+export default {
+ Layout,
+ NotFound: () => 'custom 404', // <- this is a Vue 3 functional component
+ enhanceApp({ app, router, siteData }) {
+ // app is the Vue 3 app instance from `createApp()`. router is VitePress'
+ // custom router. `siteData`` is a `ref`` of current site-level metadata.
+ }
+}
+```
+
+...where the `Layout` component could look like this:
+
+```vue
+
+
+ Custom Layout!
+
+
+```
+
+The default export is the only contract for a custom theme. Inside your custom theme, it works just like a normal Vite + Vue 3 application. Do note the theme also needs to be [SSR-compatible](/guide/using-vue.html#browser-api-access-restrictions).
+
+To distribute a theme, simply export the object in your package entry. To consume an external theme, import and re-export it from the custom theme entry:
+
+```js
+// .vitepress/theme/index.js
+import Theme from 'awesome-vitepress-theme'
+export default Theme
+```
+
+## Extending the Default Theme
+
+If you want to extend and customize the default theme, you can import it from `vitepress/theme` and augment it in a custom theme entry. Here are some examples of common customizations:
+
+### Registering Global Components
+
+```js
+// .vitepress/theme/index.js
+import DefaultTheme from 'vitepress/theme'
+
+export default {
+ ...DefaultTheme,
+ enhanceApp({ app }) {
+ // register global components
+ 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.
+
+### 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 {
+ --c-brand: #646cff;
+ --c-brand-light: #747bff;
+}
+```
+
+See [default theme CSS variables](https://github.com/vuejs/vitepress/blob/master/src/client/theme-default/styles/vars.css) that can be overridden.
+
+### Layout Slots
+
+The default theme's `` component has a few slots that can be used to inject content at certain locations of the page. Here's an example of injecting a component into the top of the sidebar:
+
+```js
+// .vitepress/theme/index.js
+import DefaultTheme from 'vitepress/theme'
+import MyLayout from './MyLayout.vue'
+
+export default {
+ ...DefaultTheme,
+ // override the Layout with a wrapper component that injects the slots
+ Layout: MyLayout
+}
+```
+
+```vue
+
+
+
+
+
+
+ My custom sidebar top content
+
+
+
+```
+
+Full list of slots available in the default theme layout:
+
+- `navbar-search`
+- `sidebar-top`
+- `sidebar-bottom`
+- `page-top-ads`
+- `page-top`
+- `page-bottom`
+- `page-bottom-ads`
+- Only when `home: true` is enabled via frontmatter:
+ - `home-hero`
+ - `home-features`
+ - `home-footer`
diff --git a/docs/guide/using-vue.md b/docs/guide/using-vue.md
index daa70775..fae01ee2 100644
--- a/docs/guide/using-vue.md
+++ b/docs/guide/using-vue.md
@@ -1,59 +1,12 @@
-# Using Vue in Markdown
-
-## Browser API Access Restrictions
-
-Because VitePress applications are server-rendered in Node.js when generating static builds, any Vue usage must conform to the [universal code requirements](https://ssr.vuejs.org/en/universal.html). In short, make sure to only access Browser / DOM APIs in `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 built-in `` component:
-
-``` md
-
-
-
-```
-
-Note this does not fix components or libraries that access Browser APIs **on import**. To use code that assumes a browser environment on import, you need to dynamically import them in proper lifecycle hooks:
-
-``` vue
-
-```
-
-If your module `export default` a Vue component, you can register it dynamically:
-
-```vue
-
-
-
+---
+sidebarDepth: 3
+---
-
-```
-
-**Also see:**
+# Using Vue in Markdown
-- [Vue.js > Dynamic Components](https://v3.vuejs.org/guide/component-dynamic-async.html)
+In VitePress, each markdown file is compiled into HTML and then processed as a Vue Single-File Component. This means you can use any Vue features inside the markdown, including dynamic templating, using Vue components, or arbitrary in-page Vue component logic by adding a `
+
+{{ page }}
```
**Output**
-``` json
+```json
{
"path": "/using-vue.html",
"title": "Using Vue in Markdown",
@@ -111,7 +69,7 @@ By default, fenced code blocks are automatically wrapped with `v-pre`. To displa
**Input**
-``` md
+```md
::: v-pre
`{{ This will be displayed as-is }}`
:::
@@ -129,9 +87,13 @@ When you need to have more flexibility, VitePress allows you to extend your auth
### Importing components in markdown
-If your components are going to be used in only a few places, the recommended way to use them is to importing the components in the file where it is used.
+If your components are going to be used in only a few places, the recommended way to use them is to importing the components in the file where it is used.
```md
+
+
# Docs
This is a .md using a custom component
@@ -141,15 +103,11 @@ This is a .md using a custom component
## More docs
...
-
-
```
### Registering global components in the theme
-If the components are going to be used across several pages in the docs, they can be registered globally in the theme (or as part of extending the default VitePress theme). Check out the [Customization Guide](./customization.md) for more information.
+If the components are going to be used across several pages in the docs, they can be registered globally in the theme (or as part of extending the default VitePress theme). Check out the [Theming Guide](./theming.md) for more information.
In `.vitepress/theme/index.js`, the `enhanceApp` function receives the Vue `app` instance so you can [register components](https://v3.vuejs.org/guide/component-registration.html#component-registration) as you would do in a regular Vue application.
@@ -180,9 +138,9 @@ Make sure a custom component’s name either contains a hyphen or is in PascalCa
You can use Vue components in the headers, but note the difference between the following syntaxes:
-| Markdown | Output HTML | Parsed Header |
-|--------|-------------|----------------|
-| # text <Tag/>
| `text
` | `text` |
+| Markdown | Output HTML | Parsed Header |
+| ------------------------------------------------------- | ----------------------------------------- | ------------- |
+| # text <Tag/>
| `text
` | `text` |
| # text \`<Tag/>\`
| `text <Tag/>
` | `text ` |
The HTML wrapped by `` will be displayed as-is; only the HTML that is **not** wrapped will be parsed by Vue.
@@ -208,7 +166,7 @@ npm install -D stylus
Then you can use the following in Markdown and theme components:
-``` vue
+```vue
diff --git a/src/client/theme-default/components/HomeFeatures.vue b/src/client/theme-default/components/HomeFeatures.vue
index 8b9349f4..c435248e 100644
--- a/src/client/theme-default/components/HomeFeatures.vue
+++ b/src/client/theme-default/components/HomeFeatures.vue
@@ -1,3 +1,23 @@
+
+