pull/1593/head
Xavi Lee 4 years ago
parent 9ff212508a
commit b789e4ed4f

@ -1,4 +1,4 @@
# API 参考 {#api-reference}
# 运行时 API 参考 {#runtime-api-reference}
VitePress 提供了几个内置 API 来获取数据。VitePress 还提供了一些可以全局使用的内置组件。
@ -66,11 +66,11 @@ interface Router {
- **Type**: `(path: string) => string`
将配置的 [`base`](../config/app-config#base) 添加到给定的 URL 路径。另请参阅 [Base URL](./asset-handling#base-url)。
将配置的 [`base`](/config/app-config#base) 添加到给定的 URL 路径。另请参阅 [Base URL](/guide/asset-handling#base-url)。
## `<Content />`
`<Content />` 组件显示渲染的 markdown 内容。这在[创建你自己的主题时](./theme-introduction)很有用。
`<Content />` 组件显示渲染的 markdown 内容。这在[创建你自己的主题时](/guide/customization-intro)很有用。
```vue
<template>

@ -154,6 +154,10 @@ interface MarkdownOptions extends MarkdownIt.Options {
// Enable line numbers in code block.
lineNumbers?: boolean
// Add support for your own languages.
// https://github.com/shikijs/shiki/blob/main/docs/languages.md#supporting-your-own-languages-with-shiki
languages?: Shiki.ILanguageRegistration
// markdown-it-anchor plugin options.
// See: https://github.com/valeriangalliat/markdown-it-anchor#usage
anchor?: anchorPlugin.AnchorOptions

@ -87,17 +87,23 @@ export default {
```ts
type NavItem = NavItemWithLink | NavItemWithChildren
type NavItemWithLink = {
interface NavItemWithLink {
text: string
link: string
activeMatch?: string
}
interface NavItemWithChildren {
interface NavItemChildren {
text?: string
items: NavItemWithLink[]
activeMatch?: string
}
interface NavItemWithChildren {
text?: string
items: (NavItemChildren | NavItemWithLink)[]
activeMatch?: string
}
```
## sidebar

@ -40,7 +40,7 @@
<img :src="theme.logoPath" />
```
在这种情况下,建议使用 VitePress 提供的 [`withBase` 辅助函数](./api#withbase) 来引用静态资源:
在这种情况下,建议使用 VitePress 提供的 [`withBase` 辅助函数](/api/#withbase) 来引用静态资源:
```vue
<script setup>

@ -0,0 +1,49 @@
## Basic Usage
```js
export default {
load() {
return {
data: 'hello'
}
}
}
```
```js
export default {
async load() {
return (await fetch('...')).json()
}
}
```
## Generating Data Based On Local Files
```js
import { readDirSync } from 'node:fs'
export default {
watch: ['*.md'],
async load() {
//
}
}
```
## Typed Data
```ts
export interface Data {
// data type
}
declare const data: Data
export { data }
export default {
async load(): Promise<Data> {
// ...
}
}
```

@ -28,13 +28,13 @@
- 运行此命令来打包文档:
```sh
$ yarn docs:build
$ npm run docs:build
```
- 打包文档后,你可以通过运行命令在本地进行调试:
```sh
$ yarn docs:serve
$ npm run docs:serve
```
`serve` 命令将启动一个本地静态 Web 服务,该服务将在 `http://localhost:4173` 输出来自 `.vitepress/dist` 的文件。 这是检查生产版本在你的本地环境中是否正常的简易方法。
@ -55,7 +55,7 @@
创建一个新项目并改成以下这些设置:
- **Build Command:** `yarn docs:build`
- **Build Command:** `npm run docs:build`
- **Output Directory:** `docs/.vitepress/dist`
- **Node Version:** `14` (或者更高,默认值通常是 14 或 16但在 Cloudflare Pages 上,默认值仍然是 12所以你可能需要[修改](https://developers.cloudflare.com/pages/platform/build-configuration/))。
@ -91,10 +91,10 @@
- uses: actions/checkout@v3
with:
node-version: 16
cache: yarn
- run: yarn install --frozen-lockfile
cache: npm
- run: npm install --frozen-lockfile
- name: Build
run: yarn docs:build
run: npm run docs:build
- uses: actions/configure-pages@v2
- uses: actions/upload-pages-artifact@v1
with:
@ -108,11 +108,13 @@
请替换对应的分支名称。例如,如果你要构建的分支是 `master`,则应将上述文件中的 `main` 替换为 `master`
:::
3. 现在提交你的代码并将其推送到 `main` 分支。
3. In your repository's Settings under Pages menu item, select `GitHub Actions` in Build and deployment's Source.
4. 等待 action 完成
4. 现在提交你的代码并将其推送到 `main` 分支
5. 在 git 仓库的 Setting 选项里,选择 `gh-pages` 分支作为 GitHub Pages 的来源。现在,你的文档将在每次推送时自动部署。
5. 等待 action 完成。
6. 在 git 仓库的 Setting 选项里,选择 `gh-pages` 分支作为 GitHub Pages 的来源。现在,你的文档将在每次推送时自动部署。
## GitLab Pages
@ -129,8 +131,8 @@
paths:
- node_modules/
script:
- yarn install
- yarn docs:build
- npm install
- npm run docs:build
artifacts:
paths:
- public
@ -148,8 +150,8 @@
before_script:
- apk add git
script:
- yarn install
- yarn docs:build
- npm install
- npm run docs:build
artifacts:
paths:
- public
@ -165,7 +167,7 @@
- **`app_location`**: `/`
- **`output_location`**: `docs/.vitepress/dist`
- **`app_build_command`**: `yarn docs:build`
- **`app_build_command`**: `npm run docs:build`
## Firebase
@ -192,7 +194,7 @@
}
```
2. 执行 `yarn docs:build` 打包命令以后, 执行以下脚本进行部署:
2. 执行 `npm run docs:build` 打包命令以后, 执行以下脚本进行部署:
```sh
firebase deploy
@ -200,7 +202,7 @@
## Surge
1. 执行 `yarn docs:build` 打包命令以后,执行以下脚本进行部署:
1. 执行 `npm run docs:build` 打包命令以后,执行以下脚本进行部署:
```sh
npx surge docs/.vitepress/dist

@ -215,7 +215,7 @@ Wraps in a <div class="vp-raw">
- Install required deps with your preferred package manager:
```sh
$ yarn add -D postcss postcss-prefix-selector
$ npm install -D postcss postcss-prefix-selector
```
- Create a file named `docs/.postcssrc.cjs` and add this to it:

@ -138,6 +138,25 @@ export default {
`activeMatch` 应为正则表达式字符串,但你必须将其定义为字符串。我们不能在这里使用实际的 RegExp 对象,因为它在构建时不可序列化。
:::
### Customize link's "target" and "rel" attributes
By default, VitePress automatically determines `target` and `rel` attributes based on whether the link is an external link. But if you want, you can customize them too.
```js
export default {
themeConfig: {
nav: [
{
text: 'Merchandise',
link: 'https://www.thegithubshop.com/',
target: '_self',
rel: 'sponsored'
}
]
}
}
```
## 社交链接 {#social-links}
点击这里查看支持的 [`socialLinks`](../config/theme-config#sociallinks).

@ -1,29 +1,43 @@
# 上下页链接 {#prev-next-link}
当你想定义上一个/下一个链接上显示与侧边栏不同的文本时,可以通过配置来自定义上下页链接。
You can customize the text and link for the previous and next pages (shown at doc footer). This is helpful if you want a different text there than what you have on your sidebar. Additionally, you may find it useful to disable the footer or link to a page that is not included in your sidebar.
## 上页 {#prev}
## prev
- 类型: `string`
- Type: `string | false | { text?: string; link?: string }`
- 详情:
- Details:
指定要在上一页的链接上显示的文本。
Specifies the text/link to show on the link to the previous page. If you don't set this in frontmatter, the text/link will be inferred from the sidebar config.
如果你没有在 frontmatter 中设置这个,文本将从侧边栏配置中推断出来。
- Examples:
- 例子:
- To customize only the text:
```yaml
---
prev: 'Get Started | Markdown'
---
```
```yaml
---
prev: 'Get Started | Markdown'
---
```
## 下页 {#next}
- To customize both text and link:
- 类型: `string`
```yaml
---
prev:
text: 'Markdown'
link: '/guide/markdown'
---
```
- 详情:
- To hide previous page:
`prev` 同理
```yaml
---
prev: false
---
```
## next
Same as `prev` but for the next page.

@ -36,7 +36,7 @@
### 获取站点和页面数据 {#access-to-site-page-data}
你可以在 `<script>` 里使用 [`useData` 辅助函数](./api#usedata) 并在页面里绑定数据。
你可以在 `<script>` 里使用 [`useData` 辅助函数](/api/#usedata) 并在页面里绑定数据。
**输入**
@ -104,7 +104,7 @@ This is a .md using a custom component
### 在主题中注册全局组件 {#registering-global-components-in-the-theme}
如果要在文档中的多个页面中使用组件,则可以在主题中全局注册它们 (或作为默认 VitePress 主题扩展的一部分)。查看[主题指南](./theme-introduction)了解更多信息。
如果要在文档中的多个页面中使用组件,则可以在主题中全局注册它们 (或作为默认 VitePress 主题扩展的一部分)。查看[自定义指南](./customization-intro)了解更多信息。
`.vitepress/theme/index.js` 中,`enhanceApp` 函数接收 Vue `app` 实例,因此你可以在常规的 Vue 应用程序中 [注册组件](https://vuejs.org/guide/components/registration.html) 。
@ -197,7 +197,7 @@ export default {
## 内置的组件 {#built-in-components}
VitePress 提供了内置的 Vue 组件,例如 `ClientOnly``OutboundLink`,查看[全局组件指南](./api) 了解更多信息。
VitePress 提供了内置的 Vue 组件,例如 `ClientOnly``OutboundLink`,查看[全局组件指南](/api/) 了解更多信息。
**参见:**

@ -1,57 +1,45 @@
# VitePress 是什么? {#what-is-vitepress}
# What is VitePress?
VitePress 基于 [Vite](https://vitejs.dev/) 构建,是 [VuePress](https://vuepress.vuejs.org/) 的小兄弟。
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<!-- TODO: showcase page? -->. 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.
::: warning
VitePress 目前处于 `alpha` 状态。它已经适合开箱即用地组织文档,但是具体配置以及和主题相关的 API 仍然可能在小的版本之间发生变化。
:::
## Developer Experience
## 动机 {#motivation}
VitePress aims to provide a great Developer Experience (DX) when working with Markdown content.
我们喜欢 VuePress v1但是它是基于 Webpack 构建的,对于一个只有几个页面的简单文档站点来说,启动开发服务器所花费的时间让人难以忍受。即使是 HMR 更新也可能需要数秒才能在浏览器中反映出来。
- **[Vite-Powered:](https://vitejs.dev/)** instant server start, with edits always instantly reflected (<100ms) without page reload.
这是因为 VuePress v1 是一个基于 Webpack 的应用。即使只有两页,它也是一个完整的正在编译的 Webpack 项目 (包括所有主题源文件)。当项目有很多页面时,将会变得更慢——每个页面都必须先完全编译,然后才能显示内容!
- **[Built-in Markdown Extensions:](/guide/markdown)** Frontmatter, tables, syntax highlighting... you name it. Specifically, VitePress provides many advanced features for working with code blocks, making it ideal for highly technical documentation.
顺便说一句Vite 很好地解决了这些问题:几乎即时启动的服务器,按需编译——只编译正在运行的页面以及闪电般的 HMR。另外随着时间的推移我在 VuePress v1 中注意到了一些额外的设计问题,但由于需要大量的重构,所以一直没有时间修复。
- **[Vue-Enhanced Markdown](/guide/using-vue):** each Markdown page is also a Vue [Single-File Component](https://vuejs.org/guide/scaling-up/sfc.html), thanks to Vue template's 100% syntax compatibility with HTML. You can embed interactivity in your static content using Vue templating features or imported Vue components.
现在,有了 Vite 和 Vue 3是时候重新思考“基于 Vue 的静态站点生成器”到底能做什么了。
## Performance
## 相对与 VuePress v1 的改进 {#improvements-over-vuepress-v1}
Unlike many traditional SSGs, a website generated by VitePress is in fact a [Single Page Application](https://en.wikipedia.org/wiki/Single-page_application) (SPA).
这是几点相对于 VuePress v1 的改进...
- **Fast Initial Load**
### 使用 Vue 3 {#it-uses-vue-3}
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.
利用 Vue 3 改进的模板静态分析来尽可能地对静态内容进行字符串化。静态内容作为字符串文字而不是 JavaScript 渲染函数代码——因此 JS 解析成本要低得多并且hydration (HTML 添加交互的过程) 也变得更快。
- **Fast Post-load Navigation**
> Hydration 一般指的是给服务器 返回的 HTML 添加交互的过程,它是在浏览器中执行的将静态 HTML 页面转为动态页面的技术
More importantly, the SPA model leads to better user experience **after** the initial load. Subsequent navigation within the site will no longer cause a full page reload. Instead, the incoming page's content will be fetched and dynamically updated. VitePress also automatically pre-fetches page chunks for links that are within viewport. In most cases, post-load navigation will feel instant.
注意,你依然可以在 Markdown 使用Vue 组件VitePress 在应用优化的同时编译器会自动进行静态/动态分离,所以无需考虑这个问题。
- **Interactivity Without Penalty**
### 使用 Vite 作为引擎 {#it-uses-vite-under-the-hood}
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.
- 更快的本地服务启动
- 更快的热更新
- 更快的打包 (内部使用 Rollup)
## Theming & Extensibility
### 更小的页面体积 {#lighter-page-weight}
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.
Vue 3 的 tree-shaking + Rollup 代码拆分
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.
- 不使用 vue-router因为 VitePress 的需求非常简单和具体 - 使用简单的自定义 router (200 行以下代码) 代替。
## What About VuePress?
### 其他不同 {#other-differences}
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.
VitePress 使用更少的配置VitePress 旨在减少当前 VuePress 的复杂性,并从根本上使用极简主义风格重新开始。
The API difference between VitePress and VuePress mostly lies in theming and customization. If you are using VuePress 1 with the default theme, it should be relatively straightforward to migrate to VitePress.
VitePress 只针对那些支持原生 ES 模块导入的浏览器。它鼓励使用原生的 JavaScript 而不进行转译,并使用 CSS 变量进行主题设计。
## 这会成为未来的下一个 vuepress 吗? {#will-this-become-the-next-vuepress-in-the-future}
我们已经有了 [vuepress-next](https://github.com/vuepress/vuepress-next),这将是 VuePress 的下一个主要版本。它还比 VuePress v1 做了很多改进,现在也支持 Vite。
VitePress 与当前的 VuePress 生态系统 (主要是主题和插件) 不兼容。总体思路是VitePress 将拥有一个更精简的主题 API (更偏向 JavaScript API 而不是文件布局约定),并且可能没有插件 (可以在主题中完成所有定制)。
关于这个话题有一个[正在进行的讨论](https://github.com/vuejs/vitepress/discussions/548)。有兴趣的话请留下你的想法!
There has also been effort invested into VuePress 2, which also supports Vue 3 and Vite with more compatibility with VuePress 1. However, maintaining two SSGs in parallel isn't sustainable, so the Vue team has decided to focus on VitePress as the main recommended SSG in the long run.

@ -10,8 +10,8 @@ hero:
tagline: 简单、强大、性能极佳。就是你想要的现代 SSG 框架!
actions:
- theme: brand
text: 快速上手
link: /zh/guide/getting-started
text: 认识 VitePress
link: /zh/guide/what-is-vitepress
- theme: alt
text: GitHub
link: https://github.com/vuejs/vitepress

Loading…
Cancel
Save