mirror of https://github.com/vuejs/vitepress
Kia King Ishii
3 years ago
parent
200c80289f
commit
0e5f1e4dd5
@ -0,0 +1,3 @@
|
||||
<template>
|
||||
<span>⚡</span>
|
||||
</template>
|
||||
@ -1,3 +1,66 @@
|
||||
# Introduction
|
||||
|
||||
Here we plan to describe all about configurations. What the difference between app config and theme config, how to access them within markdown or in Vue Component and such.
|
||||
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
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
||||
```js
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
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:
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
// Type is `DefaultTheme.Config`
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
If you use a custom theme and want type checks for the theme config, you'll need to use `defineConfigWithTheme` instead, and pass the config type for your custom theme via a generic argument:
|
||||
|
||||
```ts
|
||||
import { defineConfigWithTheme } from 'vitepress'
|
||||
import { ThemeConfig } from 'your-theme'
|
||||
|
||||
export default defineConfigWithTheme<ThemeConfig>({
|
||||
themeConfig: {
|
||||
// Type is `ThemeConfig`
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
@ -0,0 +1,92 @@
|
||||
# API Reference
|
||||
|
||||
VitePress offers several built in API to let you access app data. VitePress also comes with few built-in component that can be used globally.
|
||||
|
||||
The helper 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://vuejs.org/guide/introduction.html#composition-api) 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.footer.copyright }}</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/app-configs#base) to a given URL path. Also see [Base URL](./asset-handling#base-url).
|
||||
|
||||
## `<Content />`
|
||||
|
||||
The `<Content />` component displays the rendered markdown contents. Useful [when creating your own theme](./theme-introduction).
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<h1>Custom Layout!</h1>
|
||||
<Content />
|
||||
</template>
|
||||
```
|
||||
|
||||
## `<ClientOnly />`
|
||||
|
||||
The `<ClientOnly />` 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
|
||||
<ClientOnly>
|
||||
<NonSSRFriendlyComponent />
|
||||
</ClientOnly>
|
||||
```
|
||||
@ -0,0 +1,55 @@
|
||||
# Asset Handling
|
||||
|
||||
All Markdown files are compiled into Vue components and processed by [Vite](https://github.com/vitejs/vite). You can, **and should**, reference any assets using relative URLs:
|
||||
|
||||
```md
|
||||
|
||||
```
|
||||
|
||||
You can reference static assets in your markdown files, your `*.vue` components in the theme, styles and plain `.css` files either using absolute public paths (based on project root) or relative paths (based on your file system). The latter is similar to the behavior you are used to if you have used `vue-cli` or webpack's `file-loader`.
|
||||
|
||||
Common image, media, and font filetypes are detected and included as assets automatically.
|
||||
|
||||
All referenced assets, including those using absolute paths, will be copied to the dist folder with a hashed file name in the production build. Never-referenced assets will not be copied. Similar to `vue-cli`, image assets smaller than 4kb will be base64 inlined.
|
||||
|
||||
All **static** path references, including absolute paths, should be based on your working directory structure.
|
||||
|
||||
## Public Files
|
||||
|
||||
Sometimes you may need to provide static assets that are not directly referenced in any of your Markdown or theme components (for example, favicons and PWA icons). The `public` directory under project root can be used as an escape hatch to provide static assets that either are never referenced in source code (e.g. `robots.txt`), or must retain the exact same file name (without hashing).
|
||||
|
||||
Assets placed in `public` will be copied to the root of the dist directory as-is.
|
||||
|
||||
Note that you should reference files placed in `public` using root absolute path - for example, `public/icon.png` should always be referenced in source code as `/icon.png`.
|
||||
|
||||
## Base URL
|
||||
|
||||
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).
|
||||
|
||||
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:
|
||||
|
||||
```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
|
||||
<img :src="theme.logoPath" />
|
||||
```
|
||||
|
||||
In this case it is recommended to wrap the path with the [`withBase` helper](./api#withbase) provided by VitePress:
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
import { withBase, useData } from 'vitepress'
|
||||
|
||||
const { theme } = useData()
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<img :src="withBase(theme.logoPath)" />
|
||||
</template>
|
||||
```
|
||||
@ -0,0 +1,23 @@
|
||||
# Configuration
|
||||
|
||||
Without any configuration, the page is pretty minimal, and the user has no way to navigate around the site. To customize your site, let's first create a `.vitepress` directory inside your docs directory. This is where all VitePress-specific files will be placed. Your project structure is probably like this:
|
||||
|
||||
```
|
||||
.
|
||||
├─ docs
|
||||
│ ├─ .vitepress
|
||||
│ │ └─ config.js
|
||||
│ └─ index.md
|
||||
└─ package.json
|
||||
```
|
||||
|
||||
The essential file for configuring a VitePress site is `.vitepress/config.js`, which should export a JavaScript object:
|
||||
|
||||
```js
|
||||
export default {
|
||||
title: 'Hello VitePress',
|
||||
description: 'Just playing around.'
|
||||
}
|
||||
```
|
||||
|
||||
Learn everything about VitePress configuration at [configuration page](../config/introduction).
|
||||
@ -0,0 +1,67 @@
|
||||
# Getting Started
|
||||
|
||||
This section will help you build a basic VitePress documentation site from ground up. If you already have an existing project and would like to keep documentation inside the project, start from Step 3.
|
||||
|
||||
## Step. 1
|
||||
|
||||
Create and change into a new directory.
|
||||
|
||||
```bash
|
||||
$ mkdir vitepress-starter && cd vitepress-starter
|
||||
```
|
||||
|
||||
## Step. 2
|
||||
|
||||
Initialize with your preferred package manager.
|
||||
|
||||
```bash
|
||||
$ yarn init
|
||||
```
|
||||
|
||||
## Step. 3
|
||||
|
||||
Install VitePress.
|
||||
|
||||
```bash
|
||||
$ yarn add --dev vitepress
|
||||
```
|
||||
|
||||
## Step. 4
|
||||
|
||||
Create your first document.
|
||||
|
||||
```bash
|
||||
$ mkdir docs && echo '# Hello VitePress' > docs/index.md
|
||||
```
|
||||
|
||||
## Step. 5
|
||||
|
||||
Add some scripts to `package.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
...
|
||||
"scripts": {
|
||||
"docs:dev": "vitepress dev docs",
|
||||
"docs:build": "vitepress build docs",
|
||||
"docs:serve": "vitepress serve docs"
|
||||
},
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
## Step. 6
|
||||
|
||||
Serve the documentation site in the local server.
|
||||
|
||||
```bash
|
||||
$ yarn docs:dev
|
||||
```
|
||||
|
||||
VitePress will start a hot-reloading development server at `http://localhost:3000`.
|
||||
|
||||
## What's next?
|
||||
|
||||
By now, you should have a basic but functional VitePress documentation site.
|
||||
|
||||
When your documentation site starts to take shape, be sure to read the [deployment guide](./deploying).
|
||||
@ -0,0 +1,179 @@
|
||||
# Theme Introduction
|
||||
|
||||
VitePress comes with its own default theme, and provides a way to customize it, or evenr create your own theme. At this page, we'll go through the basics of theme customizations.
|
||||
|
||||
## Using a Custom Theme
|
||||
|
||||
You can enable a custom theme by adding the `.vitepress/theme/index.js` file (the "theme entry file").
|
||||
|
||||
```
|
||||
.
|
||||
├─ 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 should export the theme as its default export:
|
||||
|
||||
```js
|
||||
// .vitepress/theme/index.js
|
||||
import Layout from './Layout.vue'
|
||||
|
||||
export default {
|
||||
Layout,
|
||||
|
||||
// this is a Vue 3 functional component
|
||||
NotFound: () => 'custom 404',
|
||||
|
||||
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
|
||||
<!-- .vitepress/theme/Layout.vue -->
|
||||
<template>
|
||||
<h1>Custom Layout!</h1>
|
||||
|
||||
<!-- this is where markdown content will be rendered -->
|
||||
<Content />
|
||||
</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](./using-vue#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 {
|
||||
--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.
|
||||
|
||||
### 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 from './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>
|
||||
```
|
||||
|
||||
Or you could use render function as well.
|
||||
|
||||
```js
|
||||
// .vitepress/theme/index.js
|
||||
import DefaultTheme from 'vitepress/theme'
|
||||
import MyComponent from './MyComponent.vue'
|
||||
|
||||
export default {
|
||||
...DefaultTheme,
|
||||
Layout() {
|
||||
return h(DefaultTheme.Layout, null, {
|
||||
'sidebar-top': () => h(MyComponent)
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Full list of slots available in the default theme layout:
|
||||
|
||||
- Only when `layout: 'home'` is enabled via frontmatter:
|
||||
- `home-hero-before`
|
||||
- `home-hero-after`
|
||||
- `home-features-before`
|
||||
- `home-features-after`
|
||||
|
After Width: | Height: | Size: 139 KiB |
|
After Width: | Height: | Size: 223 KiB |
|
After Width: | Height: | Size: 37 KiB |
Loading…
Reference in new issue