mirror of https://github.com/vuejs/vitepress
Evan You
4 years ago
parent
a81b9e0ff1
commit
e50ba18fbe
@ -0,0 +1,95 @@
|
|||||||
|
# API Reference
|
||||||
|
|
||||||
|
## Helper Methods
|
||||||
|
|
||||||
|
The following 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.
|
||||||
|
|
||||||
|
Methods that start with `use*` indicates that it is a [Vue 3 Composition API](https://v3.vuejs.org/guide/composition-api-introduction.html) function that can only be used inside `setup()` or `<script setup>`.
|
||||||
|
|
||||||
|
### `useData`
|
||||||
|
|
||||||
|
Returns page-specific data. The returned object has the following type:
|
||||||
|
|
||||||
|
```ts
|
||||||
|
interface VitePressData {
|
||||||
|
site: Ref<SiteData>
|
||||||
|
page: Ref<PageData>
|
||||||
|
theme: Ref<any> // themeConfig from .vitepress/config.js
|
||||||
|
frontmatter: Ref<PageData['frontmatter']>
|
||||||
|
title: Ref<string>
|
||||||
|
description: Ref<string>
|
||||||
|
lang: Ref<string>
|
||||||
|
localePath: Ref<string>
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<script setup>
|
||||||
|
import { useData } from 'vitepress'
|
||||||
|
const { theme } = useData()
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<template>
|
||||||
|
<h1>{{ theme.heroText }}</h1>
|
||||||
|
</template>
|
||||||
|
```
|
||||||
|
|
||||||
|
### `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<void>
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### `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.
|
||||||
|
|
||||||
|
### `<Content/>`
|
||||||
|
|
||||||
|
The `<Content/>` component displays the rendered markdown contents. Useful [when creating your own theme](https://vitepress.vuejs.org/guide/customization.html).
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<template>
|
||||||
|
<h1>Custom Layout!</h1>
|
||||||
|
<Content />
|
||||||
|
</template>
|
||||||
|
```
|
||||||
|
|
||||||
|
### `<ClientOnly/>`
|
||||||
|
|
||||||
|
The `<ClientOnly/>` component renderes 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
|
||||||
|
<ClientOnly>
|
||||||
|
<NonSSRFriendlyComponent />
|
||||||
|
</ClientOnly>
|
||||||
|
```
|
||||||
@ -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
|
|
||||||
<!-- .vitepress/theme/Layout.vue -->
|
|
||||||
<template>
|
|
||||||
<h1>Custom Layout!</h1>
|
|
||||||
<Content /><!-- make sure to include markdown outlet -->
|
|
||||||
</template>
|
|
||||||
```
|
|
||||||
|
|
||||||
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
|
|
||||||
}
|
|
||||||
```
|
|
||||||
@ -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 `<title>` label used for the current page.
|
|
||||||
|
|
||||||
## $description
|
|
||||||
|
|
||||||
The content value of the `<meta name= "description" content= "...">` 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
|
|
||||||
<img :src="$withBase('/foo.png')" alt="foo" />
|
|
||||||
```
|
|
||||||
@ -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<SiteData>
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The theme entry file shoud 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 like this:
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<!-- .vitepress/theme/Layout.vue -->
|
||||||
|
<template>
|
||||||
|
<h1>Custom Layout!</h1>
|
||||||
|
<Content /><!-- this is where markdown content will be rendered -->
|
||||||
|
</template>
|
||||||
|
```
|
||||||
|
|
||||||
|
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 `<Layout/>` 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 fro './MyLayout.vue'
|
||||||
|
|
||||||
|
export default {
|
||||||
|
...DefaultTheme,
|
||||||
|
// override the Layout with a wrapper component that injects the slots
|
||||||
|
Layout: MyLayout
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<!--.vitepress/theme/MyLayout.vue-->
|
||||||
|
<script setup>
|
||||||
|
import DefaultTheme from 'vitepress/theme'
|
||||||
|
const { Layout } = DefaultTheme
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<template>
|
||||||
|
<Layout>
|
||||||
|
<template #sidebar-top>
|
||||||
|
My custom sidebar top content
|
||||||
|
</template>
|
||||||
|
</Layout>
|
||||||
|
</template>
|
||||||
|
```
|
||||||
|
|
||||||
|
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`
|
||||||
Loading…
Reference in new issue