VuePress Hope主题

目录

VuePress

VuePress 是一个以 Markdown 为中心的静态网站生成器。你可以使用 Markdown 来书写内容 (如文档、博客等) ，然后 VuePress 会帮助你生成一个静态网站来展示它们。

VuePress 工作原理

一个 VuePress 站点本质上是一个由 Vue 和 Vue Router

驱动的单页面应用 (SPA)。

路由会根据你的 Markdown 文件的相对路径来自动生成。每个 Markdown 文件都通过 markdown-it

编译为 HTML ，然后将其作为 Vue 组件的模板。因此，你可以在 Markdown 文件中直接使用 Vue 语法，便于你嵌入一些动态内容。

• 在开发过程中，我们启动一个常规的开发服务器 (dev-server) ，并将 VuePress 站点作为一个常规的 SPA。
• 在构建过程中，我们会为 VuePress 站点创建一个服务端渲染 (SSR) 的版本，然后通过虚拟访问每一条路径来渲染对应的 HTML。

VuePress 官方文档：VuePress

VuePress页面

VuePress 是以 Markdown 为中心的。你项目中的每一个 Markdown 文件都是一个单独的页面

路由

默认情况下，页面的路由路径是根据你的 Markdown 文件的相对路径决定的。

假设这是你的 Markdown 文件所处的目录结构：

└─ docs
   ├─ guide
   │  ├─ getting-started.md
   │  └─ README.md
   ├─ contributing.md
   └─ README.md

将 docs 目录作为你的 sourceDir ，例如你在运行 vuepress dev docs 命令。此时，你的 Markdown 文件对应的路由路径为:

应的路由路径为:

相对路径	路由路径
/README.md	/
/contributing.md	/contributing.html
/guide/README.md	/guide/
/guide/page.md	/guide/page.html

Frontmatter

Markdown 文件可以包含一个 YAML Frontmatter 。Frontmatter 必须在 Markdown 文件的顶部，并且被包裹在一对三短划线中间。下面是一个基本的示例：

---
lang: zh-CN
title: 页面的标题
description: 页面的描述
---

你肯定注意到 Frontmatter 中的字段和 VuePress 配置文件中的站点配置十分类似。你可以通过 Frontmatter 来覆盖当前页面的 lang, title, description 等属性。因此，你可以把 Frontmatter 当作页面级作用域的配置。

同样的，VuePress 有一些内置支持的 Frontmatter 字段，而你使用的主题也可能有它自己的特殊 Frontmatter 。

提示

前往 Frontmatter 参考 查看 VuePress 支持的 Frontmatter 配置。

前往 配置 > Frontmatter 查看 vuepress-theme-hope 的 Frontmatter 配置。

内容

页面的主要内容是使用 Markdown 书写的。VuePress 首先会将 Markdown 转换为 HTML ，然后将 HTML 作为 Vue 单文件组件的 <template> 。

借助 markdown-it 和 Vue 模板语法的能力，基础的 Markdown 可以得到很多的扩展功能。接下来，前往 Markdown 章节来了解 VuePress 中 Markdown 的扩展功能。

内置 Markdown 拓展

语法扩展

VuePress 会使用 markdown-it 来解析 Markdown 内容，因此可以借助于 markdown-it 插件来实现 语法扩展 。

本章节将会介绍 VuePress 内置支持的 Markdown 语法扩展。你也可以通过 markdown 和 extendsMarkdown 来配置这些内置扩展、加载更多 markdown-it 插件、实现你自己的扩展等。

内置

由 markdown-it 内置支持:

• 表格 (GFM)
• 删除线 (GFM)

标题锚点

你可能已经注意到，当你把鼠标放在各个章节的标题上时，会显示出一个 # 锚点。点击这个 # 锚点，可以直接跳转到对应章节。

提示

标题锚点扩展由 markdown-it-anchor 支持。

配置参考: markdown.anchor

链接

在你使用 Markdown 的 链接语法 时， VuePress 会为你进行一些转换。

以我们文档的源文件为例:

└─ src
    └─ zh
       ├─ cookbook
       │  └─ vuepress
       │     ├─ markdown.md <- 我们在这里
       │     └─ README.md
       ├─ guide
       │  └─ README.md
       ├─ contribution.md
       └─ README.md

原始 Markdown:

<!-- 相对路径 -->

[首页](../../README.md)  
[贡献指南](../../contribution.md)  
[VuePress 配置](./config.md)

<!-- 绝对路径 -->

[指南](/zh/guide/README.md)  
[配置参考 > 多语言](/zh/config/i18n.md)

<!-- URL -->

[GitHub](https://github.com)

转换为

<template>
  <RouterLink to="/v2/zh/">首页</RouterLink>
  <RouterLink to="/v2/zh/contribution.html">贡献指南</RouterLink>
  <RouterLink to="/v2/zh/cookbook/vuepress/config.html"
    >VuePress 配置</RouterLink
  >
  <RouterLink to="/v2/zh/guide/">指南</RouterLink>
  <RouterLink to="/v2/zh/reference/config.html#links"
    >配置参考 &gt; 多语言</RouterLink
  >
  <a href="https://github.com" target="_blank" rel="noopener noreferrer"
    >GitHub</a
  >
</template>

渲染为

首页
贡献指南
VuePress 配置
指南
配置参考 > 多语言
GitHub

解释:

• 内部链接会被转换为 <RouterLink> 以便进行 SPA 导航。
• 指向 .md 文件的内部链接会被转换为目标页面的 路由路径，并且支持绝对路径和相对路径。
• 外部链接会被添加 target="_blank" rel="noopener noreferrer" 属性。

建议:

对于内部链接，尽可能使用相对路径而不是绝对路径。

• 相对路径是指向目标文件的有效链接，在你的编辑器或者代码仓库中浏览源文件时也可以正确跳转。
• 相对路径在不同 locales 下都是一致的，这样在翻译你的内容时就不需要修改 locale 路径了。
• 在使用绝对路径时，如果你站点的 base 不是 "/"，你需要手动添加 base 或者使用 base helper。

提示

链接扩展是由我们的内置插件支持的。

配置参考: markdown.links

Emoji

你可以在你的 Markdown 内容中输入 :EMOJICODE: 来添加 Emoji 表情。

前往 emoji-cheat-sheet 来查看所有可用的 Emoji 表情和对应代码。

输入:

VuePress 2 已经发布 :tada: ！

输出:

VuePress 2 已经发布 🎉 ！

提示

Emoji 扩展由 markdown-it-emoji 支持。

配置参考: markdown.emoji

目录

如果你想要把当前页面的目录添加到 Markdown 内容中，你可以使用 [[toc]] 语法。

输入:

[[toc]]

输出:

• 语法扩展
  • 内置
  • 标题锚点
  • 链接
  • Emoji
  • 目录
  • 代码块
  • 导入代码块
• 在 Markdown 中使用 Vue
  • 模板语法
  • 组件
• 注意事项
  • 已废弃的 HTML 标签

目录中的标题将会链接到对应的 标题锚点，因此如果你禁用了标题锚点，可能会影响目录的功能。

提示

目录扩展是由我们的内置插件支持的，该扩展 Fork 并修改自 markdown-it-toc-done-right。

配置参考: markdown.toc

代码块

下列代码块扩展是在 Node 端进行 Markdown 解析的时候实现的。这意味着代码块并不会在客户端被处理。

行高亮

你可以在代码块添加行数范围标记，来为对应代码行进行高亮:

输入:

```ts {1,6-8}
import type { UserConfig } from "@vuepress/cli";
import { defaultTheme } from "@vuepress/theme-default";

export const config: UserConfig = {
  title: "你好， VuePress",

  theme: defaultTheme({
    logo: "https://vuejs.org/images/logo.png",
  }),
};
```

输出:（此处可能无法渲染）

import type { UserConfig } from "@vuepress/cli";
import { defaultTheme } from "@vuepress/theme-default";

export const config: UserConfig = {
  title: "你好， VuePress",

  theme: defaultTheme({
    logo: "https://vuejs.org/images/logo.png",
  }),
};

行数范围标记的例子:

• 行数范围: {5-8}
• 多个单行: {4,7,9}
• 组合: {4,7-13,16,23-27,40}

提示

行高亮扩展是由我们的内置插件支持的，该扩展 Fork 并修改自 markdown-it-highlight-lines。

配置参考: markdown.code.highlightLines

行号

你肯定已经注意到在代码块的最左侧会展示行号。这个功能是默认启用的，你可以通过配置来禁用它。

你可以在代码块添加 :line-numbers / :no-line-numbers 标记来覆盖配置项中的设置。

输入:

```ts
// 行号默认是启用的
const line2 = "This is line 2";
const line3 = "This is line 3";
```

```ts:no-line-numbers
// 行号被禁用
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

输出: (此处可能无法渲染)

// 行号默认是启用的
const line2 = "This is line 2";
const line3 = "This is line 3";

// 行号被禁用
const line2 = 'This is line 2'
const line3 = 'This is line 3'

提示

行号扩展是由我们的内置插件支持的。

配置参考: markdown.code.lineNumbers

添加 v-pre

由于 模板语法可以在 Markdown 中使用，它也同样可以在代码块中生效。

为了避免你的代码块被 Vue 编译， VuePress 默认会在你的代码块添加 v-pre

指令。这一默认行为可以在配置中关闭。

你可以在代码块添加 :v-pre / :no-v-pre 标记来覆盖配置项中的设置。

注意

模板语法的字符有可能会被语法高亮器解析，比如 "Mustache" 语法 (即双花括号) 。因此，就像下面的例子一样，在某些语言中 :no-v-pre 可能并不能生效。

如果你无论如何都想在这种语言中使用 Vue 语法，你可以尝试禁用默认的语法高亮，然后在客户端实现你的自定义代码高亮。

输入:

```md
<!-- 默认情况下，这里会被保持原样 -->

1 + 2 + 3 = {{ 1 + 2 + 3 }}
```

```md:no-v-pre
<!-- 这里会被 Vue 编译 -->
1 + 2 + 3 = {{ 1 + 2 + 3 }}
```

```js:no-v-pre
// 由于 JS 代码高亮，这里不会被正确编译
const onePlusTwoPlusThree = {{ 1 + 2 + 3 }}
```

输出: (此处可能无法渲染)

<!-- 默认情况下，这里会被保持原样 -->

1 + 2 + 3 = {{ 1 + 2 + 3 }}

<!-- 这里会被 Vue 编译 -->
1 + 2 + 3 = 6

// 由于 JS 代码高亮，这里不会被正确编译
const onePlusTwoPlusThree = {{ 1 + 2 + 3 }}

提示

v-pre 扩展是由我们的内置插件支持的。

配置参考: markdown.code.vPre

导入代码块

你可以使用下面的语法，从文件中导入代码块:

<!-- 最简单的语法 -->

@[code](../foo.js)

如果你只想导入这个文件的一部分:

<!-- 仅导入第 1 行至第 10 行 -->

@[code{1-10}](../foo.js)

代码语言会根据文件扩展名进行推断，但我们建议你显式指定:

<!-- 指定代码语言 -->

@[code js](../foo.js)

实际上，[] 内的第二部分会被作为代码块标记来处理，因此在上面 代码块 章节中提到的语法在这里都可以支持:

<!-- 行高亮 -->

@[code js{2,4-5}](../foo.js)

下面是一个复杂的例子:

• 导入 "../foo.js" 文件的第 3 行至第 10 行
• 指定语言为 "js"
• 对导入代码的第 3 行进行高亮，即 "../foo.js" 文件的第 5 行
• 禁用行号

@[code{3-10} js{3}:no-line-numbers](../foo.js)

需要注意的是，路径别名在导入代码语法中不会生效。你可以通过下面的配置来自行处理路径别名:

import { getDirname, path } from "@vuepress/utils";

const __dirname = getDirname(import.meta.url);

export default {
  markdown: {
    importCode: {
      handleImportPath: (str) =>
        str.replace(/^@src/, path.resolve(__dirname, "path/to/src")),
    },
  },
};

<!-- 会被解析至 'path/to/src/foo.js' -->

@[code](@src/foo.js)

提示

导入代码扩展是由我们的内置插件支持的。

配置参考: markdown.importCode

在 Markdown 中使用 Vue

这一章节会介绍 Vue 在 Markdown 中一些基本用法。

可以前往 Cookbook > Markdown 和 Vue SFC

来了解更多内容。

模板语法

我们知道:

• Markdown 中允许使用 HTML。
• Vue 模板语法是和 HTML 兼容的。

这意味着， Markdown 中允许直接使用 Vue 模板语法。

输入:

一加一等于: {{ 1 + 1 }}

<span v-for="i in 3"> span: {{ i }} </span>

输出:

一加一等于: 2

span: 1 span: 2 span: 3

组件

你可以在 Markdown 中直接使用 Vue 组件。

输入:

这是默认主题内置的 `<Badge />` 组件 <Badge text="演示" />

输出:

这是默认主题内置的 <Badge /> 组件 演示

提示

前往 内置组件 查看所有内置组件。

前往 默认主题 > 内置组件 查看默认主题中的所有内置组件。

注意事项

已废弃的 HTML 标签

已废弃的 HTML 标签默认不允许在 VuePress 的 Markdown 中使用，比如 <center> 和 <font> 等。

这些标签不会被 Vue 模板编译器识别成原生 HTML 标签。相反，Vue 会尝试将这些标签解析为 Vue 组件，而显然这些组件通常是不存在的。

你应该尽量避免使用已废弃的 HTML 标签。不过，如果你无论如何都要使用这些标签的话，可以尝试下面两种方法之一:

• 添加一个 v-pre 指令来跳过这个元素和它的子元素的编译过程。注意所有的模板语法也都会失效。
• 设置 compilerOptions.isCustomElement 来告诉 Vue 模板编译器不要尝试作为组件来解析它们。
  • 对于 @bundler-webpack ，设置 vue.compilerOptions
  • 对于 @bundler-vite ，设置 vuePluginOptions.template.compilerOptions

文件结构介绍

.
├── docs → 由你指定的文档文件夹
│    │
│    ├── .vuepress (可选的) → 用于存放全局的配置、组件、静态资源等
│    │    │
│    │    ├── dist (默认的) → 构建输出目录
│    │    │
│    │    ├── public (可选的) → 静态资源目录
│    │    │
│    │    ├── styles (可选的) → 用于存放样式相关的文件
│    │    │
│    │    ├── config.{js,ts} (可选的) → 配置文件的入口文件
│    │    │
│    │    └── client.{js,ts} (可选的) → 客户端文件
│    │
│    ├── ... → 其他项目文档
│    │
│    └── README.md → 项目主页
│
└── package.json → Nodejs 配置文件

注意

请注意 VuePress 对目录大小写敏感。

VuePress 配置

配置文件

如果没有任何配置，你的 VuePress 站点仅有一些最基础的功能。为了更好地自定义你的网站，让我们首先在你的文档目录下创建一个 .vuepress 目录，所有 VuePress 相关的文件都将会被放在这里。你的项目结构可能是这样:

├─ docs
│  ├─ .vuepress
│  │  └─ config.js
│  └─ README.md
├─ .gitignore
└─ package.json

VuePress 站点的基本配置文件是 .vuepress/config.js ，但也同样支持 TypeScript 配置文件。你可以使用 .vuepress/config.ts 来得到更好的类型提示。

一个基础的配置文件是这样的:

:::

< ts

import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  // 站点配置
  lang: "zh-CN",
  title: "你好， VuePress ！",
  description: "这是我的第一个 VuePress 站点",

  // 主题
  theme: hopeTheme({
    // 主题配置
    logo: "https://vuejs.org/images/logo.png",
  }),
});

< js

import { hopeTheme } from "vuepress-theme-hope";

export default {
  // 站点配置
  lang: "zh-CN",
  title: "你好， VuePress ！",
  description: "这是我的第一个 VuePress 站点",

  // 主题
  theme: hopeTheme({
    // 主题配置
    logo: "https://vuejs.org/images/logo.png",
  }),
};

:::

提示

前往 配置参考 查看所有 VuePress 配置。

配置作用域

站点配置

站点配置的意思是，无论你使用什么主题，这些配置项都可以生效。

我们知道，每一个站点都应该有它的 lang, title 和 description 等属性，因此 VuePress 内置支持了这些属性的配置。

主题配置

主题配置将会被 VuePress 主题来处理，所以它取决于你使用的主题是什么。

对于 vuepress-theme-hope 来说，你应该导入 hopeTheme 并设置 设置 theme: hopeTheme(options)。

注意

如果你没有设置 VuePress 配置的 theme 配置项，则代表使用的是默认主题。

客户端配置文件

在大多数情况下，配置文件已经足够帮助你配置好你的 VuePress 站点。不过，有些时候用户们可能希望直接添加一些客户端代码。 VuePress 通过客户端配置文件来支持这种需求：

├─ docs
│  ├─ .vuepress
│  │  ├─ client.js   <--- 客户端配置文件
│  │  └─ config.js   <--- 配置文件
│  └─ README.md
├─ .gitignore
└─ package.json

一个基础的客户端配置文件是这样的：

import { defineClientConfig } from "@vuepress/client";

export default defineClientConfig({
  enhance({ app, router, siteData }) {},
  setup() {},
  rootComponents: [],
});

提示

和配置文件不同，客户端配置文件不能通过命令行接口的选项来指定。

可以前往 深入 > Cookbook > 客户端配置的使用方法 来了解更多信息。

插件

介绍

借助于 插件 API ， VuePress 插件可以为你提供各种不同的功能。

社区插件

社区用户创建了很多插件，并将它们发布到了 NPM 上。 VuePress 团队也在 [@vuepress](https://www.npmjs.com/search?q=%40vuepress keywords%3Aplugin)

Scope 下维护了一些官方插件。查看插件本身的文档可以获取更详细的指引。

一般而言，你需要将插件放入到 plugins

配置项中来使用它。举例来说，你可以使用 @vuepress/plugin-google-analytics 来使用 Google Analytics :

import { googleAnalyticsPlugin } from "@vuepress/plugin-google-analytics";

export default {
  plugins: [
    googleAnalyticsPlugin({
      id: "G-XXXXXXXXXX",
    }),
  ],
};

提示

大部分插件只能使用一次，如果同一个插件被多次使用，那么只有最后一次会生效。

然而，部分插件是可以被多次使用的 (例如 @vuepress/plugin-container)，你应该查看插件本身的文档来获取详细指引。

本地插件

如果你想要使用自己的插件，但是又不想发布它，你可以创建一个本地插件。

推荐你直接将 配置文件 作为插件使用，因为 几乎所有的插件 API 都可以在配置文件中使用，这在绝大多数场景下都更为方便。

但是如果你在配置文件中要做的事情太多了，你可以考虑将它们提取到单独的插件中，然后在你的配置文件中使用它们:

import myPlugin from "./path/to/my-plugin.js";

export default {
  plugins: [myPlugin()],
};

前往 深入 > 开发插件 学习如何开发你自己的插件。

主题配置

VuePress 主题为你提供了布局、样式和其他功能，帮助你专注于 Markdown 内容的写作。

默认主题

VuePress 有一个开箱即用的默认主题，正使用在你当前正在浏览的文档网站上。

如果你不指定要使用的主题，那么就会自动使用默认主题。

为了配置默认主题，你需要在你的配置文件中通过 theme 配置项来使用它:

import { defaultTheme } from "vuepress";

export default {
  theme: defaultTheme({
    // 默认主题配置
    navbar: [
      {
        text: "首页",
        link: "/",
      },
    ],
  }),
};

默认主题为文档网站提供了基础且实用的功能，你可以前往 默认主题配置参考 获取全部的配置列表。

然而，你可能觉得默认主题不够出色，又或者你不想搭建一个文档网站，而是一个其他类型的网站，比如博客。此时，你可以尝试使用社区主题或者创建本地主题。

社区主题

社区用户创建了很多主题，并将它们发布到了 NPM 上。查看主题本身的文档可以获取更详细的指引。

本地主题

如果你想要使用自己的自定义主题，但是又不想发布它，你可以创建一个本地主题。前往 深入 > 开发主题 学习如何开发你自己的主题。