跳至主要內容

VuePress Hope主题

VuePress Hope主题

目录

快速上手

主题介绍

主题初衷

制作本主题的初衷是发现 VuePress 默认的主题只是一个提供基础文档布局的主题。

例如，它不会为 SEO 优化注入元标记，也不会生成 Sitemap 来帮助搜索引擎索引文档的内容。

VuePress 虽然在一定程度上扩展了 Markdown 语法，但仍然缺少一些常用的功能，如文本对齐、标记、流程图、公式、展示等，同时默认主题提供的一些功能较弱或缺失 ，比如图片预览，深色模式等。

在这种情况下，vuepress-theme-hope 和一些系列插件就应运诞生。

主题不仅在默认主题的基础上大幅提高美观性，同时搭配各种插件，在各种细节与功能上为 VuePress 提供全方位的增强。

一个拥有插件和强大主题的项目

vuepress-theme-hope/vuepress-theme-hope 虽然标明了其为主题仓库，但它同时包含了十多个同样功能完善且强大的插件。每一个插件也都是由 Mr.Hope 精心开发，功能足够强大，可以自由搭配默认主题或者第三方主题单独使用。

而基于这样十几个插件，Mr.Hope 才可以自信的说 vuepress-theme-hope 是“一个带有成吨功能的强大主题”。它也可以看作是 VuePress 所有主题中，功能最多，覆盖最全面的主题。

设计目标

  • 强大且独立的功能

    我们将每个功能提取到一个插件中，以便用户可以在其他主题中使用它们或单独自定义它们的行为。

  • 最小化配置

    如果可能，所有功能都会尝试生成默认值，因此你可以在零配置或最小配置下使用它们。

    这有助于减少你的迁移或学习成本，同时直接享受它们的便利。

  • 改进的布局

    主题界面已经完全重构，以提供可定制和漂亮的布局。

  • 可拆分

    借助 Vue3 的组合 API，主题在保持强大的同时充分实现了“Tree-shaking”。

    主题将只运行你想要的功能，而不会因其他功能而变慢或影响打包大小。

因何强大

更丰富的内容

主题为 Markdown 提供了大量的扩展语法支持，让你在正文插入更多的内容。

总之，任何人都可以享受 Markdown 增强语法带来的便利。

UI 改进

布局改进

搜索功能

完整的博客支持

主题引入了完整的博客支持，你可以启用全新的 博客主页。

搜索引擎增强

  • 提供 SEO 增强，会自动注入网站信息以完整支持 OGP 与 JSON-LD 协议，增强搜索引擎索引。
  • 提供 Sitemap 生成
  • 提供 PWA 支持，使你的站点可被安装。

其他

安装/使用

安装

在 [dir] 文件夹内新建 vuepress-theme-hope 项目:

# < pnpm
pnpm create vuepress-theme-hope [dir]

# < yarn
yarn create vuepress-theme-hope [dir]

# < npm
npm init vuepress-theme-hope [dir]

要将 vuepress-theme-hope 作为文档构建器添加到现有项目中，请在项目根目录中运行以下命令:

# < pnpm
pnpm create vuepress-theme-hope add [dir]

# < yarn
yarn create vuepress-theme-hope add [dir]

# < npm
npm init vuepress-theme-hope add [dir]

注

这里的 [dir] 是一个参数，你需要使用真实的文件夹名称替换它，例如 docs、blog 或其他你喜欢的名称。

使用

请在配置文件中导入并使用 hopeTheme 以使用 vuepress-theme-hope。

// < TS
// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    // 此处放置主题配置
  }),
});

// < JS
// .vuepress/config.js
import { hopeTheme } from "vuepress-theme-hope";

export default {
  theme: hopeTheme({
    // 此处放置主题配置
  }),
};

你可以查看 本文档配置 作为一个配置参考。

Markdown

VuePress 主要从 Markdown 文件生成页面。因此，你可以使用它轻松生成文档或博客站点。

你应该创建和编写 Markdown 文件，以便 VuePress 可以根据文件结构将它们转换为不同的页面。

Markdown 介绍

如果你是一个新手，还不会编写 Markdown，请先阅读 Markdown 介绍 和 Markdown 演示。

Markdown 配置

VuePress 通过 Frontmatter 为每个 Markdown 页面引入配置。

相关信息

Frontmatter 是 VuePress 中很重要的一个概念，如果你不了解它，你需要阅读 Frontmatter 介绍。

Markdown 扩展

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

VuePress 扩展

为了丰富文档写作，VuePress 对 Markdown 语法进行了扩展。

关于这些扩展，请阅读 内置 Markdown 扩展。

主题扩展

通过 vuepress-plugin-md-enhance，主题扩展了更多 Markdown 语法，提供更加丰富的写作功能。

自定义容器

安全的在 Markdown 中使用 。

::: v-pre

安全的在 Markdown 中使用 {{ variable }}。

:::

::: info 自定义标题

信息容器

:::

::: tip 自定义标题

提示容器

:::

::: warning 自定义标题

警告容器

:::

::: danger 自定义标题

危险容器

:::

::: details 自定义标题

详情容器

:::
选项卡
::: tabs

@tab 标题 1

<!-- tab 1 内容 -->

@tab 标题 2

<!-- tab 2 内容 -->

@tab:active 标题 3

<!-- tab 3 将会被默认激活 -->

<!-- tab 3 内容 -->

:::
代码块

此功能和选项卡功能相同，但它是专门为代码块构建的

代码选项卡只会渲染 @tab 标记后的代码块，其他 Markdown 内容将被忽略。

自定义对齐
::: center
要居中的段落
:::

::: right
要居右的段落
:::
属性支持
< 内联示例

## Hello World {#say-hello-world}

![img](link/to/image.png) {.full-width}

一个包含文字的段落。 {#p .a .b align=center customize-attr="content with spaces"}

包含 `行内代码`{.inline-code} 和 ![favicon](/favicon.ico){.image} 的文字，也支持 _强调_{.inline-emphasis} 和 **加粗**{.inline-bold}。也包括块

< 代码块示例 ---------------------------------------------------------

```js {.fence}
const a = 1;
```

< 表格示例 ---------------------------------------------------------

| 表格 |
| ---- |
| 内容 |

{.md-table}

< 嵌套列表示例 ---------------------------------------------------------

- 列表内容{.list-item}

  - 嵌套列表内容
    {.nested}

{.list-wrapper}
上下角标
- 19^th^
- H~2~O

(可以使用 \ 来转义 ^ 和 ~)
脚注
脚注 1 链接[^first]。

脚注 2 链接[^second]。

行内的脚注^[行内脚注文本] 定义。

重复的页脚定义[^second]。

[^first]: 脚注 **可以包含特殊标记**

    也可以由多个段落组成

[^second]: 脚注文字。
标记
VuePress Theme Hope ==非常== 强大!
任务列表
- [ ] 计划 A
- [x] 计划 B
图片增强
![GitHub Light](/assets/image/github-light.svg#gh-dark-mode-only)
![GitHub Dark](/assets/image/github-dark.svg#gh-light-mode-only)

![GitHub Light](/assets/image/github-light.svg#dark)
![GitHub Dark](/assets/image/github-dark.svg#light)

支持为图片设置颜色模式和大小

卡片
图表
::: chart %标题%

```json
{
  // 此处为图表配置
}
```

:::
Echarts
::: echarts %标题%

```json
{
  // 此处为 ECharts 图表配置
}
```

:::
流程图

注意

由于 flowchart.js

不再维护，此功能已弃用。

你应该尝试改用 Mermaid 流程图。

Mermaid
Tex 语法
导入文件
样式化

交互演示

Vue 交互演示

幻灯片
链接到当前文件 0
没有文件链接到当前文件