VuePress Hope主题

目录

小白教程

准备教程

运行环境

Node.js® 是一个基于 Chrome V8 引擎 的 JavaScript 运行时环境。

你需要下载并在你的电脑上安装最新的长期维护版。

下载Node.js

略

安装Node.js

略

安装编辑器

略

Pnmp

在你安装 Node.js 之后，请安装 pnpm。

我们推荐你使用 pnpm 作为项目管理器，因为 VuePress 和 VuePress Theme Hope 都是通过 pnpm 来管理依赖的。

pnpm 的一些功能可以保证你拥有正确的依赖，并且它能加速安装。

在终端中输入下列命令安装 pnpm:

corepack enable
corepack prepare pnpm@latest --activate

创建项目

此教程将指引你创建一个 VuePress Theme Hope 项目。

选择合适的项目位置

为了避免偶然间触发一些奇怪的问题，而你自己不会解决，请尽量避免使用包含中文文字、表情符号或空格的文件路径 (如: C:\Users\小张\Desktop\VuePress 项目\Hope 主题❤️\)。

建议使用纯英文路径 (如: D:\projects\vuepress-theme-hope\)。

初始化项目

在选定的位置所在文件夹中打开终端。

请使用文件管理器打开对应文件夹，之后在上方的地址栏中输入 cmd 之后按下回车。

在终端中执行下列命令之一:

# pnpm
pnpm create vuepress-theme-hope my-docs

# yarn
yarn create vuepress-theme-hope my-docs

# npm
npm init vuepress-theme-hope my-docs

文件夹参数

这里的 my-docs 是一个参数，代表 VuePress Theme Hope 项目的文件夹名称，在本教程中，我们将项目生成至当前目录下的 my-docs 文件夹。

如果你有需求，你可以更改此参数来使用一个新文件夹名称。

中文显示

如果你的英语很不好，请在第一次选择中通过键盘 ↓ 选择 简体中文 并回车来在后续流程中使用中文进行显示。

开发服务器

如果你在模板初始化成功后选择立即启动开发服务器，稍等片刻，你就可以在浏览器地址栏输入 localhost:8080/ 访问开发服务器了。

项目指令

本教程介绍 VuePress 项目命令

常用命令

• vuepress dev [dir] 会启动一个开发服务器，以便让你在本地开发你的 VuePress 站点。
• vuepress build [dir] 会将你的 VuePress 站点构建成静态文件，以便你进行后续部署。

使用模板

如果你在使用 VuePress Theme Hope 模板，你可以在 package.json 中发现下列三个命令:

{
  "scripts": {
    "docs:build": "vuepress build src",
    "docs:clean-dev": "vuepress dev src --clean-cache",
    "docs:dev": "vuepress dev src"
  }
}

这意味着你可以使用:

• pnpm docs:dev 启动开发服务器
• pnpm docs:build 构建项目并输出
• pnpm docs:clean-dev 清除缓存并启动开发服务器

终止开发服务器

如果你需要终止开发服务器，请点击终端，并连续两次按下 Ctrl + C。

升级版本

如果你需要升级主题和 VuePress 版本，请执行以下命令：

# pnpm
pnpm dlx vp-update

# yarn
yarn dlx vp-update

# npm
npx vp-update

[warning] 注意

任何以 @vuepress/ 开头的官方包应该和 VuePress 保持相同版本。

比如，如果你正在使用 @vuepress/plugin-search 和 @vuepress/utils，你应该确保他们和 vuepress 版本相同

另外，如果你使用了其他第三方插件，请确保它兼容你要升级到的 VuePress 版本。

项目内容

本教程指引你如何在 VuePress 项目中控制内容生成。

页面的生成

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

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

由于你的项目是通过创建助手生成的，那么你会得到以下文件结构：

└─ src
   ├─ guide
   │  ├─ ...
   │  └─ page.md
   │  └─ markdown.md
   │  └─ README.md
   ├─ ...
   ├─ slide.md
   └─ README.md

你的 Markdown 文件对应的路由路径为:

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

README.md

README.md 是特例，在 Markdown 中，按照约定俗成，它会作为所在文件夹的主页。所以在渲染为网页时，它的对应路径为网页中的主页路径 index.html。

这应该很好理解。

Frontmatter

Frontmatter 是 VuePress 中很重要的一个概念，它用于承载 Markdown 文件的配置。Markdown 文件可以包含一个 YAML Frontmatter。

YAML

如果你对 YAML 也不熟悉，你可以查看 YAML 教程。

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

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

<!-- 这里是 Markdown 内容 -->

...

你肯定注意到 Frontmatter 中的字段和 VuePress 配置文件十分类似。你可以通过 Frontmatter 来覆盖当前页面的 lang, title, description 等属性。因此，你可以把 Frontmatter 当作页面级作用域的配置，它通常具有最高优先级，所作配置仅对当前页面生效。

Markdown

每一个 Markdown 文件都会被 VuePress Theme Hope 处理，将文件内容渲染为网页内容。

都会被 VuePress Theme Hope 处理，将文件内容渲染为网页内容。

Markdown 语法

如果你尚不了解 Markdown，请查看 Markdown 教程。

大概十五分钟，你就可以学会如何书写 Markdown，看完之后记得回来！

你可以尝试自己编辑 Markdown 文件来修改模板的内容。如果你已启动开发服务器，那么修改后的结果会被实时同步到开发服务器上。

Markdown 语法扩展

• VuePress 自身对 Markdown 语法进行了一些扩展，关于这些扩展的语法，详见 VuePress → Markdown。
• 主题通过 vuepress-plugin-md-enhance 额外启用了一些语法扩展，详见 指南 → Markdown。

配置项目

配置 VuePress

如果没有配置文件，一个 VuePress 项目只能按照预设实现有限的功能，所以为了更好的自定义你的网站，VuePress 提供了配置文件。

VuePress 使用文档文件夹中的 .vuepress 文件夹存放配置，所有 VuePress 相关的文件都将会被放在这里。

对于 VuePress 站点来说，.vuepress/config.ts (或 .vuepress/config.js) 是必要的配置文件。

使用 TS 配置文件

我们建议你使用 TypeScript 配置文件，以得到更好的类型提示、自动补全与错误检查。

如果你不熟悉 TypeScript，使用 JavaScript 配置文件也是可以的，但你最好使用诸如 VSCode 这种全面支持 TS/JS 语法的编辑器，以避免丢失下方提及的类型检查、自动补全与选项提示等功能。

配置文件

你需要在配置文件.vuepress/config.ts (或 .vuepress/config.js) 中，设置一个配置对象并将其导出。

为了能够得到正确的提示，我们建议从 vuepress 导入 defineUserConfig 并包裹配置对象：

（js版本略）

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";

export default defineUserConfig({
  // 此处放置配置
});

在模板中，为了避免配置文件过长，我们使用 JavaScript 原生提供的 ESM 特性，将主题配置、导航栏和侧边栏配置拆分到了单独的文件夹中。

模板将主题函数抽离到了 .vuepress/theme.js，并通过 export default 导出。

.vuepress/theme.ts:

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

// 我们默认导出了主题对象
export default hopeTheme({
  // 主题配置
});

随后在配置文件中直接引入:

.vuepress/config.ts:

// ...
// 我们在这里引入了主题
import theme from "./theme.js";

// ...

export default defineUserConfig({
  // ...

  // 这和 `theme: hopeTheme({/* 你的配置 */})` 是等价的
  theme,

  // ...
});

这也能更清晰的帮助你理解配置中的站点配置和主题配置

配置作用域

站点配置

站点配置中的配置项被 VuePress 直接读取，和主题无关且在所有主题均可生效。

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

站点配置

你可以前往 VuePress2 → 参考 → 配置 查看所有 VuePress 配置。

主题配置

主题配置是你传递给 hopeTheme 函数的对象，它将由 VuePress Theme Hope 处理。

你可以在 配置 → 主题配置 中找到全部的主题配置。

提示与检查

如果你在使用支持 TS/JS 语言特性的编辑器 (如 VSCode)，你可以很方便的得到选项提示与检查。

• 你可以将鼠标悬停在某个选项以获得提示:
  
• 如果你输入了错误的选项名称或非法的值，你会得到错误提示:
  
• 你可以在输入时得到自动补全:
  

更多

插件配置

VuePress Theme Hope 主题捆绑了一些插件，你可以在主题选项中通过 plugins.插件名称 来传递插件选项，详见 配置 → 主题插件配置。

如果你想要额外使用插件，请自行调用插件并传递插件选项，详见 VuePress → 插件。

样式配置

VuePress Theme Hope 主题按照约定俗称，使用 .vuepress/styles 文件夹存放样式配置。

你可以在此文件夹中:

• 创建 index.scss 来注入额外的 CSS 样式
• 创建 config.scss 来进行样式配置
• 创建 palette.scss 来配置颜色与布局

更多详情，详见 配置 → 样式配置。

页面配置

VuePress 支持在页面范围内通过 Markdown 文件中的 YAML Frontmatter 进行特定页面的配置，详见之前章节中的 项目内容 → Frontmatter。

项目结构

VuePress 项目结构

VuePress 只控制 VuePress 项目文件夹中的文件，也就是默认模板生成的 src 文件夹，项目下的其他文件不受 VuePress 控制。

一个基本的项目结构如下:

.
├── .github (可选的) → GitHub 配置文件存放路径
│    └── workflow → GitHub 工作流配置
│         └── docs-deploy.yml → 自动部署文档的工作流
│
├── src → 文档文件夹
│    │
│    ├── .vuepress (可选的) → VuePress 配置文件夹
│    │    │
│    │    ├── dist (默认的) → 构建输出目录
│    │    │
│    │    ├── public (可选的) → 静态资源目录
│    │    │
│    │    ├── styles (可选的) → 用于存放样式相关的文件
│    │    │
│    │    ├── config.{js,ts} (可选的) → 配置文件的入口文件
│    │    │
│    │    └── client.{js,ts} (可选的) → 客户端文件
│    │
│    ├── ... → 其他项目文档
│    │
│    └── README.md → 项目主页
│
└── package.json → Nodejs 配置文件

部署项目

构建项目

当你在本地完成项目的初步开发后，你就可以使用 pnpm docs:build 命令构建网站。

如果你在使用模板，网站内容将会输出到 VuePress 项目的 .vuepress/dist 文件夹下。这些文件就是 VuePress 的最终输出结果。

你可以将此文件夹的内容部署到你网站的服务器上。最简单的做法是上传到 GitHub 并开启 GitHub Pages。

部署到 GitHub Pages

如果你在使用模板，且在创建过程中选择了创建自动部署文档的 GitHub 工作流，那么你唯一要做的就是设置正确的 base 选项。

• 如果你准备发布到 https://<USERNAME>.github.io/，你必须将整个项目上传至 https://github.com/<USERNAME>/<USERNAME>.github.io 仓库。在这种情况下你无需进行任何更改，因为 base 默认就是 "/"。
• 如果你的仓库地址是一个普通的形如 https://github.com/<USERNAME>/<REPO> 的格式，网站将会被发布到 https://<USERNAME>.github.io/<REPO>/ ，也就是说，你需要将 base 设置为 "/<REPO>/"。

Github 教程

关于 GitHub 的相关教程，你可以参考 GitHub 简介。

其他部署方式

关于其他部署方式，请参阅 VuePress → 部署。

Gitee

如果你在使用码云，你需要注意码云的特殊仓库是 https://gitee.com/<USERNAME>/<USERNAME>。如果你推送到这个仓库，你的文档将会发布在 https://<USERNAME>.gitee.io 上。