VuePress Hope主题

自定义

此章节向你演示常见的自定义需求涉及的相关代码。

添加组件

每个 markdown 文件将在 VuePress 中转换为一个 Vue 组件，因此你可以轻松导入和使用 Vue 组件。

添加组件

自定义样式的方式

你可以在自己文档内的 .vuepress/styles 文件夹下放置三个文件进行样式配置。

index.scss: 你可以在这里通过 CSS 或 SCSS 语法放置自己的样式以对主题的外观进行修改。
填入的样式会注入到主题和插件样式的后部。
config.scss: 你可以在这里设置一些样式相关变量，包括响应式断点、容器类名、代码主题等。
palette.scss: 你可以在这里设置一些颜色和布局的相关变量，比如主题色、背景色、导航栏高度等。

上述文件支持的完整配置列表详见配置 → 样式。

详情

使用组件

本教程将指引你如何在 VuePress 项目中使用 Vue 组件与 Vue 语法。

全局导入 Vue 组件

通过 `@vuepress/plugin-register-components` 注册组件

你可以通过 @vuepress/plugin-register-components 插件来自动注册组件。

插件的使用方法详见官方文档。

通过 ClientConfigFile 注册

你可以通过创建 .vuepress/client.ts 手动注册组件。

// .vuepress/client.ts
import { defineClientConfig } from "@vuepress/client";
import MyComponent from "./MyComponent.vue";

export default defineClientConfig({
  enhance: ({ app, router, siteData }) => {
    app.component("MyComponent", MyComponent);
  },
});

在 Markdown 中使用 Vue 语法与组件

你可以直接在 Markdown 中使用 Vue 语法。关于具体的使用方式，详见 VuePress → Markdown

如果你需要在 Markdown 中导入 Vue 组件，请注意你不能使用相对路径进行导入，也不能书写多个 <script> 块。

Markdown 与 Vue SFC
每一个 Markdown 文件，首先都会编译为 HTML ，然后转换为一个 Vue 单文件组件 (SFC) 。换句话说，你可以像写 Vue SFC 一样来写 Markdown 文件:
<script> 和 <style> 标签会直接被当作 Vue SFC 中的标签。换句话说，它们是从 <template> 标签中提升到了 SFC 的顶层。
所有 <script> 和 <style> 标签的以外的内容，会先被编译为 HTML ，然后被当作 Vue SFC 的 <template> 标签。
由于 Vue 单文件组件只能包含一个 <script> 标签，你应该避免在 VuePress Markdown 中使用多于一个 <script> 标签。
另外由于 Markdown 会被转换为缓存目录下的 Vue 单文件组件，任何相对路径的导入会在 Vue SFC 中失效。

为了正确导入自己的组件，你需要为它们创建别名，你可以通过 alias 选项实现这一点:

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

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

export default {
  alias: {
    "@MyComponent": path.resolve(__dirname, "components/MyComponent.vue"),
  },
};

<MyComponent />

<script setup lang="ts">
import MyComponent from "@MyComponent";
</script>

这固然复杂一些，但是如果你所使用的组件仅在这个页面使用，这样导入更具有优势:

全局导入意味着组件代码需要在 VuePress 初始化，也就是访问首个页面时载入
在 Markdown 中导入会使得组件代码包含在页面代码中，这样它仅会在访问这个页面时被导入

修改字体

此页面指导你如何自定义主题字体。

字体族

对于常见的字体族，一般可以分为 衬线体[1] 和 无衬线体[2]。

中文字体
对于中文字体来说，常见的无衬线体有黑体、微软雅黑等，而常见的衬线体包括楷体、宋体、仿宋等。

修改主题字体

主题在 .vuepress/styles/palette.scss 中提供了 $font-family、$font-family-heading 和 $font-family-mono 三个变量控制字体。

$font-family: 普通文本上使用的字体
$font-family-heading: 用于标题元素的字体
$font-family-mono: 代码上使用的字体

默认情况下，主题在普通文本上使用无衬线体。

使用衬线体
如果你更喜欢衬线体，你可以自行修改 $font-family 为你想要的字体。
中文博客下最常使用的字体是 Adobe 发布的思源宋体[3]，因为它具有非常宽松的协议。当然，思源宋体并不存在于大多设备上，所以你可能需要导入这个字体。你可以通过 GitHub 下载该字体引入或直接使用 Google Font CDN。
如下字体族是我们推荐的衬线体首选:
$font-family: 'Georgia, -apple-system, "Nimbus Roman No9 L", "PingFang SC", "Hiragino Sans GB", "Noto Serif SC", "Microsoft Yahei", "WenQuanYi Micro Hei", "ST Heiti", sans-serif';

后备字体

由于不同平台、不同操作系统以及不同的安装方式 (slim/full) 会导致字体库中的字体数量以及类别产生较大差异，你应该尽可能地设置多个字体，并确保后备字体[4]存在。

最佳实践
后备字体[4:1]可以确保你的网站在不同操作系统以及安装了不同字体的设备上显示良好。

字体库

你可以在 Google Fonts 中找到更多字体，并可以在线预览与下载。

请在网页中搜索并选择你想要的字体与粗细，然后点击右侧的 Select 按钮，将其添加到你的选择列表中，之后点击右上角的按钮查看你的收藏字体，并获取链接在 VuePress 的配置文件中导入。

我们假定你选择了思源宋体 (Noto Serif SC) 字体的 400，500，700 字体，点击右上角按钮后，Google 会在侧边栏给出下方的代码:

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  href="https://fonts.googleapis.com/css2?family=Noto+Serif+SC:wght@400;500;700&display=swap"
  rel="stylesheet"
/>

font-family: "Noto Serif SC", serif;

那么你需要做的就是在 VuePress 配置文件中添加如下代码导入并使用它们:

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

export default defineUserConfig({
  // ...

  head: [
    // ...

    // 导入相应链接
    ["link", { rel: "preconnect", href: "https://fonts.googleapis.com" }],
    [
      "link",
      { rel: "preconnect", href: "https://fonts.gstatic.com", crossorigin: "" },
    ],
    [
      "link",
      {
        href: "https://fonts.googleapis.com/css2?family=Noto+Serif+SC:wght@400;500;700&display=swap",
        rel: "stylesheet",
      },
    ],
  ],

  // ...
});

同时在调色板文件中修改 $font-family 变量:

// .vuepress/styles/palette.scss

// 应用字体
$font-family: '"Noto Serif SC", serif';

这样你就可以在网站中使用思源宋体字体了。

思源宋体 Demo

人人生而自由

人人生而自由，在尊严和权利上一律平等。他们赋有理性和良心，并应以弟兄关系的精神相对待。

相关简介: https://www.zhihu.com/topic/19559432/intro
相关简介: https://www.zhihu.com/topic/19559433/intro
基于「开源字体授权发布」，并且在文档中说明可以基于其源代码进行二次修改后使用 (商用或者个人使用)，所以没有任何版权问题。
摘自维基百科
后备字体 (Fallback font) 是指在当时显示的字型缺乏某些字元时，被用于显示缺失字元的字体。因为其作为显示的最后一道防线，后备字体应该尽可能包含所有 Unicode 字元。
当缺失字元没有后备字体用于显示时，通常会将缺失字元改为黑色方块、白色空心方块、问号、Unicode 占位字元(U+FFFD)显示，或者干脆略过该字元。在实务上，像是 CSS 等支援字体列表依序显示的系统，通常会将一或多套后备字体置入列表最后，以防止缺字的情况发生

修改布局

此教程指导你如何修改主题布局。

修改主题配置

主题提供了很多布局有关的选项，供你自定义主题的布局，关于这些选项详见主题配置 → 布局。

修改 SCSS 变量

主题断点

主题在不同屏幕宽度下会自动响应式应用不同布局，如果你需要修改这些断点，可以在配置文件中修改，

// .vuepress/styles/config.scss

// 修改桌面布局的断点
$pc = 1280px;

配置文件 .vuepress/styles/config.scss 以及断点变量 $pc、$laptop、$pad、$tablet、$mobile 的具体介绍详见主题配置 → 样式。

主题布局尺寸

主题在调色板文件中提供了常见尺寸的变量，你可以在调色版文件中修改这些变量，以达到修改布局尺寸的目的。

// .vuepress/styles/palette.scss

// 修改导航栏高度
$navbar-height = 80px;

调色板文件 .vuepress/styles/palette.scss 以及布局变量的介绍详见主题配置 → 样式。

修改其他布局

如果你希望改变主题布局，但主题并未提供相关选项时，你可以考虑如下方法：

通过 CSS

如果你对主题的样式不满意，你可以通过样式文件对主题组件的样式进行调节。
注
为了覆盖原有样式，你需要使用相同或更高优先级的选择器或者直接使用 !important。
如果你希望去掉一些功能，你可以在样式文件中通过 display: none 隐藏相关元素。
注
样式文件为项目目录下的 .vuepress/styles/index.scss，详见主题配置 → 样式

通过覆盖组件

所有的主题组件都是通过别名进行注册与调用的，这意味着你可以通过覆盖组件别名，将主题的任一组件替换为你自己的组件。

如果你只是想在页面的特定位置添加新内容，那么你可以通过替换组件，并引用原组件通过原组件的插槽来实现。

组件别名、组件插槽与替换方式详见高级 → 替换主题组件。

修改特效

此教程引导你如何自定义主题特效。

清除特效

主题在默认情况下，会:

使用色卡对分类、标签进行装饰
在切换页面、元素时添加动画
为主页元素添加缓入动画、以及为特性添加悬浮特效。
使用较为显眼的代码复制按钮
使用较为花哨的提示框。
在日间模式和夜间模式切换时添加渐入

如果你需要清除这些花哨的样式，请在主题选项中配置 pure: true 开启纯净模式。

同时，你可以通过控制调色板文件中的 $color-transition 和 transform-transition 来控制动画的时长:

// .vuepress/styles/palette.scss

$color-transition: 0s;
$transform-transition: 0s;

添加特效

你可以自由的通过 VuePress 提供的配置文件选项和客户端文件为你的站点添加更多特效。

如果你需要添加全局的 CSS 与 JS，请在 VuePress 配置文件中配置 head 选项。

例子

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

export default defineUserConfig({
  // ...

  head: [
    // ...

    // 导入一个外部脚本
    ["script", { src: "YOUR_SCRIPT_LINK" }],
    // 添加一段脚本
    [
      "script",
      {},
      `\
        // your script here
      `,
    ],
    // 添加一个外部 CSS
    ["link", { rel: "stylesheet", href: "YOUR_STYLE_LINK" }],
    // 添加一段样式
    // 我们不建议这么做，你应该首选使用 .vuepress/style/index.scss
    [
      "style",
      {},
      `\
        /* your style here */
      `,
    ],
  ],

  // ...
});

如果你需要添加页面级别的 CSS 与 JS，请在 Front Matter 中配置 head 选项。

---
head:
  - script: YOUR_SCRIPT_LINK
  - script:
      type: module
      src: YOUR_SCRIPT_LINK
  - style: YOUR_STYLE_LINK
  - style:
      type: text/css
      content: |
        /* your style here */
---

页面内容

...

更多全局的高级操作，可以通过客户端配置文件进行。

// .vuepress/client.ts
import { defineClientConfig } from "@vuepress/client";
import ExampleGlobalComponent from "./components/ExampleGlobalComponent.vue";
import ExampleRootComponent from "./components/ExampleRootComponent.vue";
import { setupExampleCompositionAPI } from "./composables/exampleCompositionAPI";

export default defineClientConfig({
  // 客户端增强
  enhance: ({ app }) => {
    // 注册全局组件
    app.component("ExampleGlobalComponent", ExampleGlobalComponent);
  },

  // 全局注册
  setup() {
    // 注册全局 Composition API
    setupExampleCompositionAPI();
  },

  // 全局组件
  rootComponents: [
    "ExampleRootComponent",
    // ...
  ],
});

修改颜色

此页面指导你如何自定义主题颜色。

修改内置颜色

主题通过调色板控制颜色，你可能需要分为两种情况设置你的颜色：

此颜色在日间模式和夜间模式保持不变，如主题色。
此颜色在日间模式、夜间模式下不同，如背景色、字体、边框颜色等。

调色板文件是 VuePress 项目文件夹下的 .vuepress/styles/palette.scss 文件。

对于前者，你需要在 palette.scss 中写入变量值，如：

// .vuepress/styles/palette.scss
$theme-color: #3eaf7c;

对于后者，你需要设置一个 Map，键名为 light 和 dark，值为颜色值，如：

// .vuepress/styles/palette.scss
$bg-color: (
  light: #fff,
  dark: #000,
);

所有可用的颜色变量详见主题配置 → 颜色设置。

修改其他颜色

有些时候，你可能希望修改一些不在 palette.scss 中的颜色，比如代码块的背景色，此时你可以通过开发者工具查看对应的颜色属性值是否是 CSS 变量，如果是你可以在 index.scss 中手动覆盖这一变量值:

// .vuepress/styles/index.scss

// 覆盖代码块背景色
#app {
  --code-bg-color: #000;

  html[data-theme="dark"] & {
    --code-bg-color: #222;
  }
}

如果不是，请你自己编写选择器覆盖它们:

// .vuepress/styles/index.scss

// 覆盖代码块语言字体颜色
pre[class*="language-"]::before {
  color: #fff !important;

  html[data-theme="dark"] & {
    background-color: #222 !important;
  }
}

链接到当前文件 0

没有文件链接到当前文件

VuePress Hope主题

VuePress Hope主题

目录

自定义

自定义

添加组件

自定义样式的方式

详情

使用组件

全局导入 Vue 组件

通过 @vuepress/plugin-register-components 注册组件

通过 ClientConfigFile 注册

在 Markdown 中使用 Vue 语法与组件

修改字体

字体族

修改主题字体

后备字体

字体库

人人生而自由

修改布局

修改主题配置

修改 SCSS 变量

主题断点

主题布局尺寸

修改其他布局

通过 CSS

通过覆盖组件

修改特效

清除特效

添加特效

修改颜色

修改内置颜色

修改其他颜色

通过 `@vuepress/plugin-register-components` 注册组件