From 6547b5bad0b4aaed1cce482db898252aa096a1a8 Mon Sep 17 00:00:00 2001 From: Xavi Lee Date: Thu, 16 Mar 2023 11:12:22 +0800 Subject: [PATCH] update headings --- docs/zh/guide/asset-handling.md | 8 +-- docs/zh/guide/cms.md | 6 +- docs/zh/guide/custom-theme.md | 12 ++-- docs/zh/guide/data-loading.md | 10 ++-- docs/zh/guide/deploy.md | 24 ++++---- docs/zh/guide/extending-default-theme.md | 12 ++-- docs/zh/guide/frontmatter.md | 10 ++-- docs/zh/guide/getting-started.md | 20 +++---- docs/zh/guide/i18n.md | 6 +- docs/zh/guide/markdown.md | 60 +++++++++---------- docs/zh/guide/migration-from-vitepress-0.md | 8 +-- docs/zh/guide/migration-from-vuepress.md | 10 ++-- docs/zh/guide/mpa-mode.md | 4 +- docs/zh/guide/routing.md | 28 ++++----- docs/zh/guide/ssr-compat.md | 12 ++-- docs/zh/guide/using-vue.md | 34 +++++------ docs/zh/guide/what-is-vitepress.md | 10 ++-- docs/zh/reference/cli.md | 28 ++++----- docs/zh/reference/default-theme-badge.md | 21 ++++--- docs/zh/reference/default-theme-carbon-ads.md | 2 +- docs/zh/reference/default-theme-config.md | 7 +-- docs/zh/reference/default-theme-edit-link.md | 6 +- docs/zh/reference/default-theme-footer.md | 2 +- docs/zh/reference/default-theme-home-page.md | 8 +-- .../reference/default-theme-last-updated.md | 6 +- docs/zh/reference/default-theme-layout.md | 10 ++-- docs/zh/reference/default-theme-nav.md | 12 ++-- .../default-theme-prev-next-links.md | 4 +- docs/zh/reference/default-theme-search.md | 2 +- docs/zh/reference/default-theme-sidebar.md | 8 +-- docs/zh/reference/default-theme-team-page.md | 8 +-- docs/zh/reference/frontmatter-config.md | 12 ++-- docs/zh/reference/runtime-api.md | 10 ++-- docs/zh/reference/site-config.md | 26 ++++---- 34 files changed, 221 insertions(+), 225 deletions(-) diff --git a/docs/zh/guide/asset-handling.md b/docs/zh/guide/asset-handling.md index c914bf31..e7f1cccc 100644 --- a/docs/zh/guide/asset-handling.md +++ b/docs/zh/guide/asset-handling.md @@ -1,6 +1,6 @@ -# Asset Handling +# 资源处理 {#asset-handling} -## Referencing Static Assets +## 引用静态资源 {#referencing-static-assets} All Markdown files are compiled into Vue components and processed by [Vite](https://vitejs.dev/guide/assets.html). You can, **and should**, reference any assets using relative URLs: @@ -16,7 +16,7 @@ All referenced assets, including those using absolute paths, will be copied to t All **static** path references, including absolute paths, should be based on your working directory structure. -## The Public Directory +## public 目录 {#the-public-directory} Sometimes you may need to provide static assets that are not directly referenced in any of your Markdown or theme components, or you may want to serve certain files with the original filename. Examples of such files include `robot.txt`, favicons, and PWA icons. @@ -31,7 +31,7 @@ There is one exception to this: if you have an HTML page in `public` and link to - [/pure.html](/pure.html) - -## Base URL +## 根 URL {#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). diff --git a/docs/zh/guide/cms.md b/docs/zh/guide/cms.md index 8694cf0a..dae33a46 100644 --- a/docs/zh/guide/cms.md +++ b/docs/zh/guide/cms.md @@ -2,9 +2,9 @@ outline: deep --- -# Connecting to a CMS +# 连接到 CMS {#connecting-to-a-cms} -## General Workflow +## 一般的工作流 {#general-workflow} Connecting VitePress to a CMS will largely revolve around [Dynamic Routes](./routing#dynamic-routes). Make sure to understand how it works before proceeding. @@ -51,6 +51,6 @@ Since each CMS will work differently, here we can only provide a generic workflo ``` -## Integration Guides +## 整合指南 {#integration-guides} If you have written a guide on integrating VitePress with a specific CMS, please use the "Edit this page" link below to submit it here! diff --git a/docs/zh/guide/custom-theme.md b/docs/zh/guide/custom-theme.md index 83625a23..fe019764 100644 --- a/docs/zh/guide/custom-theme.md +++ b/docs/zh/guide/custom-theme.md @@ -1,6 +1,6 @@ -# Using a Custom Theme +# 自定义主题 {#using-a-custom-theme} -## Theme Resolving +## 解析主题 {#theme-resolving} You can enable a custom theme by creating a `.vitepress/theme/index.js` or `.vitepress/theme/index.ts` file (the "theme entry file"): @@ -17,7 +17,7 @@ You can enable a custom theme by creating a `.vitepress/theme/index.js` or `.vit VitePress will always use the custom theme instead of the default theme when it detects presence of a theme entry file. You can, however, [extend the default theme](./extending-default-theme) to perform advanced customizations on top of it. -## Theme Interface +## 主题接口 {#theme-interface} A VitePress custom theme is defined as an object with the following interface: @@ -68,7 +68,7 @@ The default export is the only contract for a custom theme, and only the `Layout Inside your layout component, it works just like a normal Vite + Vue 3 application. Do note the theme also needs to be [SSR-compatible](./ssr-compat). -## Building a Layout +## 构建布局 {#building-a-layout} The most basic layout component needs to contain a [``](../reference/runtime-api#content) component: @@ -152,7 +152,7 @@ const { page, frontmatter } = useData() Consult the [Runtime API Reference](../reference/runtime-api) for everything available in theme components. In addition, you can leverage [Build-Time Data Loading](./data-loading) to generate data-driven layout - for example, a page that lists all blog posts in the current project. -## Distributing a Custom Theme +## Distributing a Custom Theme {#distributing-a-custom-theme} The easiest way to distribute a custom theme is by providing it as a [template repository on GitHub](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository). @@ -168,7 +168,7 @@ If you wish to distribute the theme as an npm package, follow these steps: 5. Provide clear instructions on how to consume your theme (see below). -## Consuming a Custom Theme +## Consuming a Custom Theme {#consuming-a-custom-theme} To consume an external theme, import and re-export it from the custom theme entry: diff --git a/docs/zh/guide/data-loading.md b/docs/zh/guide/data-loading.md index c7f7c8e6..85e16ac8 100644 --- a/docs/zh/guide/data-loading.md +++ b/docs/zh/guide/data-loading.md @@ -1,10 +1,10 @@ -# Build-Time Data Loading +# 构建时数据加载 {#build-time-data-loading} VitePress provides a feature called **data loaders** that allows you to load arbitrary data and import it from pages or components. The data loading is executed **only at build time**: the resulting data will be serialized as JSON in the final JavaScript bundle. Data loaders can be used to fetch remote data, or generate metadata based on local files. For example, you can use data loaders to parse all your local API pages and automatically generate an index of all API entries. -## Basic Usage +## 基本用法 {#basic-usage} A data loader file must end with either `.data.js` or `.data.ts`. The file should provide a default export of an object with the `load()` method: @@ -52,7 +52,7 @@ export default { } ``` -## Data from 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. @@ -130,7 +130,7 @@ import { data as posts } from './posts.data.js' ``` -### Options +### Options {#options} The default data may not suit all needs - you can opt-in to transform the data using options: @@ -171,7 +171,7 @@ export default { } ``` -## Typed Data Loaders +## Typed Data Loaders {#typed-data-loaders} When using TypeScript, you can type your loader and `data` export like so: diff --git a/docs/zh/guide/deploy.md b/docs/zh/guide/deploy.md index 3bf9c3ea..223809b2 100644 --- a/docs/zh/guide/deploy.md +++ b/docs/zh/guide/deploy.md @@ -2,7 +2,7 @@ outline: deep --- -# Deploy Your VitePress Site +# 部署 {#deploy-your-vitepress-site} The following guides are based on some shared assumptions: @@ -19,7 +19,7 @@ The following guides are based on some shared assumptions: } ``` -## Build and Test Locally +## 本地构建和测试 {#build-and-test-locally} 1. Run this command to build the docs: @@ -47,13 +47,13 @@ The following guides are based on some shared assumptions: Now the `docs:preview` method will launch the server at `http://localhost:8080`. -## Setting a Public Base Path +## 设定 public 根目录 {#setting-a-public-base-path} By default, we assume the site is going to be deployed at the root path of a domain (`/`). If your site is going to be served at a sub-path, e.g. `https://mywebsite.com/blog/`, then you need to set the [`base`](../reference/site-config#base) option to `'/blog/'` in the VitePress config. **Example:** If you're using Github (or GitLab) Pages and deploying to `user.github.io/repo/`, then set your `base` to `/repo/`. -## HTTP Cache Headers +## HTTP 缓存标头 {#http-cache-headers} If you have control over the HTTP headers on your production server, you can configure `cache-control` headers to achieve better performance on repeated visits. @@ -103,9 +103,9 @@ Note: the `vercel.json` file should be placed at the root of your **repository** ::: -## Platform Guides +## 如何部署到平台 {#platform-guides} -### Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render +### Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render Set up a new project and change these settings using your dashboard: @@ -117,7 +117,7 @@ Set up a new project and change these settings using your dashboard: Don't enable options like _Auto Minify_ for HTML code. It will remove comments from output which have meaning to Vue. You may see hydration mismatch errors if they get removed. ::: -### GitHub Pages +### GitHub Pages 1. In your theme config file, `docs/.vitepress/config.js`, set the `base` property to the name of your GitHub repository. If you plan to deploy your site to `https://foo.github.io/bar/`, then you should set base to `'/bar/'`. It should always start and end with a slash. @@ -171,7 +171,7 @@ Don't enable options like _Auto Minify_ for HTML code. It will remove comments f 6. In your repository's Settings under Pages menu item, click `Visit site`, then you can see your site. Your docs will automatically deploy each time you push. -### GitLab Pages +### GitLab Pages 1. Set `outDir` in `docs/.vitepress/config.js` to `../public`. @@ -214,7 +214,7 @@ Don't enable options like _Auto Minify_ for HTML code. It will remove comments f - main ``` -### Azure Static Web Apps +### Azure Static Web Apps {#azure-static-web-apps} 1. Follow the [official documentation](https://docs.microsoft.com/en-us/azure/static-web-apps/build-configuration). @@ -224,7 +224,7 @@ Don't enable options like _Auto Minify_ for HTML code. It will remove comments f - **`output_location`**: `docs/.vitepress/dist` - **`app_build_command`**: `npm run docs:build` -### Firebase +### Firebase {#firebase} 1. Create `firebase.json` and `.firebaserc` at the root of your project: @@ -255,7 +255,7 @@ Don't enable options like _Auto Minify_ for HTML code. It will remove comments f firebase deploy ``` -### Surge +### Surge 1. After running `npm run docs:build`, run this command to deploy: @@ -263,7 +263,7 @@ Don't enable options like _Auto Minify_ for HTML code. It will remove comments f npx surge docs/.vitepress/dist ``` -### Heroku +### Heroku 1. Follow documentation and guide given in [`heroku-buildpack-static`](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-static). diff --git a/docs/zh/guide/extending-default-theme.md b/docs/zh/guide/extending-default-theme.md index c7459923..d2a1effd 100644 --- a/docs/zh/guide/extending-default-theme.md +++ b/docs/zh/guide/extending-default-theme.md @@ -1,4 +1,4 @@ -# Extending the Default Theme +# 扩展默认主题 {#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. @@ -14,7 +14,7 @@ These advanced customizations will require using a custom theme that "extends" t Before proceeding, make sure to first read [Using a Custom Theme](./custom-theme) to understand how custom themes work. ::: -## Customizing CSS +## 自定义 CSS {#customizing-css} The default theme CSS is customizable by overriding root level CSS variables: @@ -36,7 +36,7 @@ export default DefaultTheme See [default theme CSS variables](https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css) that can be overridden. -## Using Different Fonts +## 使用自定义字体 {#using-different-fonts} VitePress uses [Inter](https://rsms.me/inter/) as the default font, and will include the fonts in the build output. The font is also auto preloaded in production. However, this may not be desirable if you want to use a different main font. @@ -88,7 +88,7 @@ export default { } ``` -## Registering Global Components +## 注册全局组件 {#registering-global-components} ```js // .vitepress/theme/index.js @@ -105,7 +105,7 @@ export default { 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 +## 布局插槽 {#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 before outline: @@ -190,7 +190,7 @@ Full list of slots available in the default theme layout: - `nav-screen-content-before` - `nav-screen-content-after` -## Overriding Internal Components +## 重写内部组件 {#overriding-internal-components} You can use Vite's [aliases](https://vitejs.dev/config/shared-options.html#resolve-alias) to replace default theme components with your custom ones: diff --git a/docs/zh/guide/frontmatter.md b/docs/zh/guide/frontmatter.md index c1856ca4..d60704c1 100644 --- a/docs/zh/guide/frontmatter.md +++ b/docs/zh/guide/frontmatter.md @@ -1,6 +1,6 @@ -# Frontmatter +# Frontmatter {#frontmatter} -## Usage +## 用法 {#usage} VitePress supports YAML frontmatter in all Markdown files, parsing them with [gray-matter](https://github.com/jonschlinkert/gray-matter). The frontmatter must be at the top of the Markdown file (before any elements including ` -# Hello +# Hello {#hello} ``` ` ``` -### Rendering Raw Content +### Rendering Raw Content {#rendering-raw-content} Params passed to the page will be serialized in the client JavaScript payload, so you should avoid passing heavy data in params, for example raw Markdown or HTML content fetched from a remote CMS. diff --git a/docs/zh/guide/ssr-compat.md b/docs/zh/guide/ssr-compat.md index 9a97c940..7b821251 100644 --- a/docs/zh/guide/ssr-compat.md +++ b/docs/zh/guide/ssr-compat.md @@ -2,13 +2,13 @@ outline: deep --- -# SSR Compatibility +# SSR 兼容性 {#ssr-compatibility} VitePress pre-renders the app in Node.js during the production build, using Vue's Server-Side Rendering (SSR) capabilities. This means all custom code in theme components are subject to SSR Compatibility. The [SSR section in official Vue docs](https://vuejs.org/guide/scaling-up/ssr.html) provides more context on what is SSR, the relationship between SSR / SSG, and common notes on writing SSR-friendly code. The rule of thumb is to only access browser / DOM APIs in `beforeMount` or `mounted` hooks of Vue components. -## `` +## `` 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: @@ -18,11 +18,11 @@ If you are using or demoing components that are not SSR-friendly (for example, c ``` -## Libraries that Access Browser API on Import +## 在导入时访问浏览器 API 的库 {#libraries-that-access-browser-api-on-import} Some components or libraries access browser APIs **on import**. To use code that assumes a browser environment on import, you need to dynamically import them. -### Importing in Mounted Hook +### 在 mounted 钩子中导入 {#importing-in-mounted-hook} ```vue ``` -### Conditional Import +### Conditional Import {#conditional-import} You can also conditionally import a dependency using the `import.meta.env.SSR` flag (part of [Vite env variables](https://vitejs.dev/guide/env-and-mode.html#env-variables)): @@ -63,7 +63,7 @@ export default { } ``` -### `defineClientComponent` +### `defineClientComponent` {#`defineclientcomponent`} VitePress provides a convenience helper for importing Vue components that access browser APIs on import. diff --git a/docs/zh/guide/using-vue.md b/docs/zh/guide/using-vue.md index 947ebeff..f0a6e36a 100644 --- a/docs/zh/guide/using-vue.md +++ b/docs/zh/guide/using-vue.md @@ -1,4 +1,4 @@ -# Using Vue in Markdown +# 在 Markdown 使用 Vue {#using-vue-in-markdown} In VitePress, each Markdown file is compiled into HTML and then processed as a [Vue Single-File Component](https://vuejs.org/guide/scaling-up/sfc.html). 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 ` -## Markdown Content +## Markdown Content {#markdown-content} The count is: {{ count }} @@ -96,11 +96,11 @@ const { page } = useData() } ``` -## Using Components +## 使用组件 {#using-components} You can import and use Vue components directly in Markdown files. -### Importing in Markdown +### 在 Markdown 中导入组件 {#importing-in-markdown} If a component is only used by a few pages, it's recommended to explicitly import them where they are used. This allows them to be properly code-split and only loaded when the relevant pages are shown: @@ -120,7 +120,7 @@ This is a .md using a custom component ... ``` -### Registering Components Globally +### 注册全局组件 {#registering-components-globally} If a component is going to be used on most of the pages, they can be registered globally by customizing the Vue app instance. See relevant section in [Extending Default Theme](./extending-default-theme#registering-global-components) for an example. @@ -128,7 +128,7 @@ If a component is going to be used on most of the pages, they can be registered Make sure a custom component's name either contains a hyphen or is in PascalCase. Otherwise, it will be treated as an inline element and wrapped inside a `

` tag, which will lead to hydration mismatch because `

` does not allow block elements to be placed inside it. ::: -### Using Components In Headers +### 在标题中使用组件 {#using-components-in-headers} You can use Vue components in the headers, but note the difference between the following syntaxes: @@ -144,7 +144,7 @@ The output HTML is accomplished by [Markdown-it](https://github.com/Markdown-it/ ::: -## Escaping +## 转义 {#escaping} You can escape Vue interpolations by wrapping them in a `` or other elements with the `v-pre` directive: @@ -178,7 +178,7 @@ Alternatively, you can wrap the entire paragraph in a `v-pre` custom container: -## Unescape in Code Blocks +## 代码块中不转义 {#unescape-in-code-blocks} By default, all fenced code blocks are automatically wrapped with `v-pre`, so no Vue syntax will be processd inside. To enable Vue-style interpolation inside fences, you can append the language with the `-vue` suffix, e.g. `js-vue`: @@ -196,18 +196,18 @@ Hello {{ 1 + 1 }} Hello {{ 1 + 1 }} ``` -## Using CSS Pre-processors +## 使用 CSS 预处理器 {#using-css-pre-processors} VitePress has [built-in support](https://vitejs.dev/guide/features.html#css-pre-processors) for CSS pre-processors: `.scss`, `.sass`, `.less`, `.styl` and `.stylus` files. There is no need to install Vite-specific plugins for them, but the corresponding pre-processor itself must be installed: ``` -# .scss and .sass +# .scss and .sass {#.scss-and-.sass} npm install -D sass -# .less +# .less {#.less} npm install -D less -# .styl and .stylus +# .styl and .stylus {#.styl-and-.stylus} npm install -D stylus ``` @@ -220,7 +220,7 @@ Then you can use the following in Markdown and theme components: ``` -## Using Teleports +## 传递组件内容 {#using-teleports} Vitepress currently has SSG support for teleports to body only. For other targets, you can wrap them inside the built-in `` component or inject the teleport markup into the correct location in your final page HTML through [`postRender` hook](../reference/site-config#postrender). diff --git a/docs/zh/guide/what-is-vitepress.md b/docs/zh/guide/what-is-vitepress.md index 7f5a8aac..f3c7b933 100644 --- a/docs/zh/guide/what-is-vitepress.md +++ b/docs/zh/guide/what-is-vitepress.md @@ -1,4 +1,4 @@ -# What is VitePress? +# VitePress 是什么？ {#what-is-vitepress} VitePress is a [Static Site Generator](https://en.wikipedia.org/wiki/Static_site_generator) (SSG) designed for building fast, content-centric websites. In a nutshell, VitePress takes your source content written in [Markdown](https://en.wikipedia.org/wiki/Markdown), applies a theme to it, and generates static HTML pages that can be easily deployed anywhere. @@ -8,7 +8,7 @@ Just want to try it out? Skip to the [Quickstart](./getting-started). -## Use Cases +## 使用场景 {#use-cases} - **Documentation** @@ -22,7 +22,7 @@ Just want to try it out? Skip to the [Quickstart](./getting-started). The official [Vue.js blog](https://blog.vuejs.org/) is a simple blog that generates its index page based on local content. -## Developer Experience +## 开发体验 {#developer-experience} VitePress aims to provide a great Developer Experience (DX) when working with Markdown content. @@ -32,7 +32,7 @@ VitePress aims to provide a great Developer Experience (DX) when working with Ma - **[Vue-Enhanced Markdown](./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. -## Performance +## 性能 {#performance} 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). @@ -48,7 +48,7 @@ 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. -## What About VuePress? +## VuePress 怎么样？ {#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/zh/reference/cli.md b/docs/zh/reference/cli.md index 0df6da0e..1d36da03 100644 --- a/docs/zh/reference/cli.md +++ b/docs/zh/reference/cli.md @@ -1,20 +1,20 @@ -# Command Line Interface +# 命令行接口 {#command-line-interface} -## `vitepress dev` +## `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 +### 用法 {#usage} ```sh -# start in current directory, omitting `dev` +# start in current directory, omitting `dev` {#start-in-current-directory,-omitting-`dev`} vitepress -# start in sub directory +# start in sub directory {#start-in-sub-directory} vitepress dev [root] ``` -### Options +### 选项 {#options} | Option | Description | | - | - | @@ -25,17 +25,17 @@ vitepress dev [root] | `--strictPort` | Exit if specified port is already in use (`boolean`) | | `--force` | Force the optimizer to ignore the cache and re-bundle (`boolean`) | -## `vitepress build` +## `vitepress build` {#`vitepress-build`} Build the VitePress site for production. -### Usage +### 用法 {#usage} ```sh vitepress build [root] ``` -### Options +### 选项 {#options} | Option | Description | | - | - | @@ -46,28 +46,28 @@ vitepress build [root] | `--minify [minifier]` | Enable/disable minification, or specify minifier to use (default: `"esbuild"`) (`boolean \| "terser" \| "esbuild"`) | | `--assetsInlineLimit ` | Static asset base64 inline threshold in bytes (default: `4096`) (`number`) | -## `vitepress preview` +## `vitepress preview` {#`vitepress-preview`} Locally preview the production build. -### Usage +### 用法 {#usage} ```sh vitepress preview [root] ``` -### Options +### 选项 {#options} | Option | Description | | - | - | | `--base ` | Public base path (default: `/`) (`string`) | | `--port ` | Specify port (`number`) | -## `vitepress init` +## `vitepress init` Start the [Setup Wizard](../guide/getting-started#setup-wizard) in current directory. -### Usage +### 用法 {#usage} ```sh vitepress init diff --git a/docs/zh/reference/default-theme-badge.md b/docs/zh/reference/default-theme-badge.md index 404d0dd4..9275d154 100644 --- a/docs/zh/reference/default-theme-badge.md +++ b/docs/zh/reference/default-theme-badge.md @@ -1,36 +1,35 @@ -# Badge +# 标记 {#badge} The badge lets you add status to your headers. For example, it could be useful to specify the section's type, or supported version. -## Usage +## 用法 {#usage} You may use the `Badge` component which is globally available. ```html -### Title -### Title +### Title +### Title ### Title ### Title ``` Code above renders like: -### Title -### Title -### Title +### Title +### Title +### Title ### Title -## Custom Children +## 自定义 `children` {#custom-children} `` accept `children`, which will be displayed in the badge. ```html -### Title custom element -``` +### Title custom element ### Title custom element -## Customize Type Color +## Customize Type Color You can customize the `background-color` of badges by overriding css variables. The following are the default values: diff --git a/docs/zh/reference/default-theme-carbon-ads.md b/docs/zh/reference/default-theme-carbon-ads.md index 1c0c170e..e2a8322a 100644 --- a/docs/zh/reference/default-theme-carbon-ads.md +++ b/docs/zh/reference/default-theme-carbon-ads.md @@ -1,4 +1,4 @@ -# Carbon Ads +# Carbon Ads {#carbon-ads} VitePress has built in native support for [Carbon Ads](https://www.carbonads.net/). By defining the Carbon Ads credentials in config, VitePress will display ads on the page. diff --git a/docs/zh/reference/default-theme-config.md b/docs/zh/reference/default-theme-config.md index a35aec2c..7e2a761a 100644 --- a/docs/zh/reference/default-theme-config.md +++ b/docs/zh/reference/default-theme-config.md @@ -1,4 +1,4 @@ -# Default Theme Config +# 默认主题配置 {#default-theme-config} Theme config lets you customize your theme. You can define theme config via the `themeConfig` option in the config file: @@ -316,7 +316,7 @@ export interface AlgoliaSearchOptions extends DocSearchProps { View full options [here](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts). -## carbonAds {#carbon-ads} +## carbonAds - Type: `CarbonAdsOptions` @@ -373,7 +373,7 @@ export interface DocFooter { Can be used to customize the dark mode switch label. This label is only displayed in the mobile view. -## sidebarMenuLabel +## sidebarMenuLabel {#sidebarmenulabel} - Type: `string` - Default: `Menu` @@ -381,7 +381,6 @@ Can be used to customize the dark mode switch label. This label is only displaye Can be used to customize the sidebar menu label. This label is only displayed in the mobile view. ## returnToTopLabel - - Type: `string` - Default: `Return to top` diff --git a/docs/zh/reference/default-theme-edit-link.md b/docs/zh/reference/default-theme-edit-link.md index c52adf4e..e9099507 100644 --- a/docs/zh/reference/default-theme-edit-link.md +++ b/docs/zh/reference/default-theme-edit-link.md @@ -1,6 +1,6 @@ -# Edit Link +# 编辑链接 {#edit-link} -## Site-Level Config +## 全局配置 {#site-level-config} Edit Link lets you display a link to edit the page on Git management services such as GitHub, or GitLab. To enable it, add `themeConfig.editLink` options to your config. @@ -49,7 +49,7 @@ export default { } ``` -## Frontmatter Config +## Frontmatter 配置 {#frontmatter-config} This can be disabled per-page using the `editLink` option on frontmatter: diff --git a/docs/zh/reference/default-theme-footer.md b/docs/zh/reference/default-theme-footer.md index e363537f..69b11c20 100644 --- a/docs/zh/reference/default-theme-footer.md +++ b/docs/zh/reference/default-theme-footer.md @@ -1,4 +1,4 @@ -# Footer +# 页脚 {#footer} VitePress will display global footer at the bottom of the page when `themeConfig.footer` is present. diff --git a/docs/zh/reference/default-theme-home-page.md b/docs/zh/reference/default-theme-home-page.md index 93de38e1..3c2b652b 100644 --- a/docs/zh/reference/default-theme-home-page.md +++ b/docs/zh/reference/default-theme-home-page.md @@ -1,4 +1,4 @@ -# Home Page +# 主页 {#home-page} VitePress default theme provides a homepage layout, which you can also see used on [the homepage of this site](../). You may use it on any of your pages by specifying `layout: home` in the [frontmatter](./frontmatter-config). @@ -10,7 +10,7 @@ layout: home However, this option alone wouldn't do much. You can add several different pre templated "sections" to the homepage by setting additional other options such as `hero` and `features`. -## Hero Section +## Hero 部分 {#hero-section} The Hero section comes at the top of the homepage. Here's how you can configure the Hero section. @@ -72,7 +72,7 @@ interface HeroAction { } ``` -### Customizing the name color +### 自定义名字的颜色 {#customizing-the-name-color} VitePress uses the brand color (`--vp-c-brand`) for the `name`. However, you may customize this color by overriding `--vp-home-hero-name-color` variable. @@ -91,7 +91,7 @@ Also you may customize it further by combining `--vp-home-hero-name-background` } ``` -## Features Section +## Features 部分 {#features-section} In Features section, you can list any number of features you would like to show right after the Hero section. To configure it, pass `features` option to the frontmatter. diff --git a/docs/zh/reference/default-theme-last-updated.md b/docs/zh/reference/default-theme-last-updated.md index e2cbb1d2..bfe072c1 100644 --- a/docs/zh/reference/default-theme-last-updated.md +++ b/docs/zh/reference/default-theme-last-updated.md @@ -1,8 +1,8 @@ -# Last Updated +# 最后更新 {#last-updated} The update time of the last content will be displayed in the lower right corner of the page. To enable it, add `lastUpdated` options to your config. -## Site-Level Config +## 全局配置 {#site-level-config} ```js export default { @@ -10,7 +10,7 @@ export default { } ``` -## Frontmatter Config +## Frontmatter 配置 {#frontmatter-config} This can be disabled per-page using the `lastUpdated` option on frontmatter: diff --git a/docs/zh/reference/default-theme-layout.md b/docs/zh/reference/default-theme-layout.md index 27426e9c..64702272 100644 --- a/docs/zh/reference/default-theme-layout.md +++ b/docs/zh/reference/default-theme-layout.md @@ -1,4 +1,4 @@ -# Layout +# 布局 {#layout} You may choose the page layout by setting `layout` option to the page [frontmatter](./frontmatter-config). There are 3 layout options, `doc`, `page`, and `home`. If nothing is specified, then the page is treated as `doc` page. @@ -8,7 +8,7 @@ layout: doc --- ``` -## Doc Layout +## doc 布局 {#doc-layout} Option `doc` is the default layout and it styles the whole Markdown content into "documentation" look. It works by wrapping whole content within `vp-doc` css class, and applying styles to elements underneath it. @@ -21,7 +21,7 @@ It also provides documentation specific features listed below. These features ar - Outline - [Carbon Ads](./default-theme-carbon-ads) -## Page Layout +## page 布局 {#page-layout} Option `page` is treated as "blank page". The Markdown will still be parsed, and all of the [Markdown Extensions](../guide/markdown) work as same as `doc` layout, but it wouldn't get any default stylings. @@ -29,10 +29,10 @@ The page layout will let you style everything by you without VitePress theme aff Note that even in this layout, sidebar will still show up if the page has a matching sidebar config. -## Home Layout +## Home 布局 {#home-layout} Option `home` will generate templated "Homepage". In this layout, you can set extra options such as `hero` and `features` to customize the content further. Please visit [Default Theme: Home Page](./default-theme-home-page) for more details. -## No Layout +## 无布局 {#no-layout} If you don't want any layout, you can pass `layout: false` through frontmatter. This option is helpful if you want a fully-customizable landing page (without any sidebar, navbar, or footer by default). diff --git a/docs/zh/reference/default-theme-nav.md b/docs/zh/reference/default-theme-nav.md index 624e9f11..65a28725 100644 --- a/docs/zh/reference/default-theme-nav.md +++ b/docs/zh/reference/default-theme-nav.md @@ -1,8 +1,8 @@ -# Nav +# 导航 {#nav} The Nav is the navigation bar displayed on top of the page. It contains the site title, global menu links, etc. -## Site Title and Logo +## 站点标题和 logo {#site-title-and-logo} By default, nav shows the title of the site referencing [`config.title`](./site-config#title) value. If you would like to change what's displayed on nav, you may define custom text in `themeConfig.siteTitle` option. @@ -37,7 +37,7 @@ export default { You can also pass an object as logo if you want to add `alt` attribute or customize it based on dark/light mode. Refer [`themeConfig.logo`](./default-theme-config#logo) for details. -## Navigation Links +## 导航链接 {#navigation-links} You may define `themeConfig.nav` option to add links to your nav. @@ -114,7 +114,7 @@ export default { } ``` -### Customize link's "active" state +### 自定义 "active" 状态 {#customize-link-s-active-state} Nav menu items will be highlighted when the current page is under the matching path. if you would like to customize the path to be matched, define `activeMatch` property and regex as a string value. @@ -138,7 +138,7 @@ export default { `activeMatch` is expected to be a regex string, but you must define it as a string. We can't use actual RegExp object here because it isn't serializable during the build time. ::: -### Customize link's "target" and "rel" attributes +### 自定义 "target" 和 "rel" 属性 {#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. @@ -157,6 +157,6 @@ export default { } ``` -## Social Links +## 社交链接 {#social-links} Refer [`socialLinks`](./default-theme-config#sociallinks). diff --git a/docs/zh/reference/default-theme-prev-next-links.md b/docs/zh/reference/default-theme-prev-next-links.md index 7befe179..05163aab 100644 --- a/docs/zh/reference/default-theme-prev-next-links.md +++ b/docs/zh/reference/default-theme-prev-next-links.md @@ -1,8 +1,8 @@ -# Prev Next Links +# 上下页链接 {#prev-next-links} 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 - Type: `string | false | { text?: string; link?: string }` diff --git a/docs/zh/reference/default-theme-search.md b/docs/zh/reference/default-theme-search.md index 26b77a29..eac09795 100644 --- a/docs/zh/reference/default-theme-search.md +++ b/docs/zh/reference/default-theme-search.md @@ -1,4 +1,4 @@ -# Search +# 搜索 {#search} VitePress supports searching your docs site using [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Refer their getting started guide. In your `.vitepress/config.ts` you'll need to provide at least the following to make it work: diff --git a/docs/zh/reference/default-theme-sidebar.md b/docs/zh/reference/default-theme-sidebar.md index 67893cf6..901c9c6f 100644 --- a/docs/zh/reference/default-theme-sidebar.md +++ b/docs/zh/reference/default-theme-sidebar.md @@ -1,4 +1,4 @@ -# Sidebar +# 侧边栏 {#sidebar} The sidebar is the main navigation block for your documentation. You can configure the sidebar menu in [`themeConfig.sidebar`](./default-theme-config#sidebar). @@ -19,7 +19,7 @@ export default { } ``` -## The Basics +## 基本用法 {#the-basics} The simplest form of the sidebar menu is passing in a single array of links. The first level item defines the "section" for the sidebar. It should contain `text`, which is the title of the section, and `items` which are the actual navigation links. @@ -93,7 +93,7 @@ export default { } ``` -## Multiple Sidebars +## 多侧边栏 {#multiple-sidebars} You may show different sidebar depending on the page path. For example, as shown on this site, you might want to create a separate sections of content in your documentation like "Guide" page and "Config" page. @@ -147,7 +147,7 @@ export default { } ``` -## Collapsible Sidebar Groups +## 可折叠的侧边栏组 {#collapsible-sidebar-groups} By adding `collapsed` option to the sidebar group, it shows a toggle button to hide/show each section. diff --git a/docs/zh/reference/default-theme-team-page.md b/docs/zh/reference/default-theme-team-page.md index 5a6e2a9e..2eba6800 100644 --- a/docs/zh/reference/default-theme-team-page.md +++ b/docs/zh/reference/default-theme-team-page.md @@ -23,11 +23,11 @@ const members = [ ] -# Team Page +# 团队页 {#team-page} If you would like to introduce your team, you may use Team components to construct the Team Page. There are two ways of using these components. One is to embed it in doc page, and another is to create a full Team Page. -## Show team members in a page +## 在页面中展示团队成员 {#show-team-members-in-a-page} You may use `` component exposed from `vitepress/theme` to display a list of team members on any page. @@ -66,7 +66,7 @@ Embedding team members in doc page is good for small size team where having dedi If you have large number of members, or simply would like to have more space to show team members, consider [creating a full team page](#create-a-full-team-page). -## Create a full Team Page +## 建立完整的团队页 {#create-a-full-team-page} Instead of adding team members to doc page, you may also create a full Team Page, similar to how you can create a custom [Home Page](./default-theme-home-page). @@ -119,7 +119,7 @@ When creating a full team page, remember to wrap all components with `` works as same as when used in a doc page. It will display list of members. -### Add sections to divide team members +### 将成员信息分成多个部分 {#add-sections-to-divide-team-members} You may add "sections" to the team page. For example, you may have different types of team members such as Core Team Members and Community Partners. You can divide these members into sections to better explain the roles of each group. diff --git a/docs/zh/reference/frontmatter-config.md b/docs/zh/reference/frontmatter-config.md index 4322d985..d0850095 100644 --- a/docs/zh/reference/frontmatter-config.md +++ b/docs/zh/reference/frontmatter-config.md @@ -2,7 +2,7 @@ outline: deep --- -# Frontmatter Config +# Frontmatter 配置 {#frontmatter-config} Frontmatter enables page based configuration. In every markdown file, you can use frontmatter config to override site-level or theme-level config options. Also, there are config options which you can only define in frontmatter. @@ -21,7 +21,7 @@ You can access frontmatter data via the `$frontmatter` global in Vue expressions {{ $frontmatter.title }} ``` -## title +## title {#title} - Type: `string` @@ -82,11 +82,11 @@ type HeadConfig = | [string, Record, string] ``` -## Default Theme Only +## 仅在默认主题生效 {#default-theme-only} The following frontmatter options are only applicable when using the default theme. -### layout +### layout - Type: `doc | home | page` - Default: `doc` @@ -103,11 +103,11 @@ layout: doc --- ``` -### hero +### hero Defines contents of home hero section when `layout` is set to `home`. More details in [Default Theme: Home Page](./default-theme-home-page). -### features +### features Defines items to display in features section when `layout` is set to `home`. More details in [Default Theme: Home Page](./default-theme-home-page). diff --git a/docs/zh/reference/runtime-api.md b/docs/zh/reference/runtime-api.md index 68bf29cc..a99c5469 100644 --- a/docs/zh/reference/runtime-api.md +++ b/docs/zh/reference/runtime-api.md @@ -1,4 +1,4 @@ -# Runtime API +# 运行时 API {#runtime-api} VitePress offers several built-in APIs to let you access app data. VitePress also comes with a few built-in components that can be used globally. @@ -6,7 +6,7 @@ The helper methods are globally importable from `vitepress` and are typically us Methods that start with `use*` indicates that it is a [Vue 3 Composition API](https://vuejs.org/guide/introduction.html#composition-api) function ("Composable") that can only be used inside `setup()` or `