主题

2025-03-06
885
3.9m

配置简介 推荐 ​

风景图

提示

Shiki24 提供了非常丰富的功能，但是很多功能默认是不开启的，需要通过配置项来选择开启或者关闭。

所有 Shiki24 配置项不会影响 VitePress 本身的配置，两者是独立生效的。

VitePress 的配置通常添加在 .vitepress/config.mts 文件中（没有请创建），而为了区分 Shiki24 的配置项，我们需要在 config.mts 同级创建 Shiki24Config.mts 文件，即路径为 .vitepress/Shiki24Config.mts。

ts
// .vitepress/Shiki24Config.mts
import { defineShiki24Config } from "shiki24/config";

// Shiki24 主题配置，所有 Shiki24 配置都放到 ... 中
export const Shiki24Config = defineShiki24Config({
  // ...
});
ts
// .vitepress/config.mts
import { defineConfig } from "vitepress";
import { Shiki24Config } from "./Shiki24Config";

// VitePress 配置
export default defineConfig({
  extends: Shiki24Config, // 注册 Shiki24 主题配置
  // ...
});

第一个代码块介绍如何添加 Shiki24 配置项，第二个代码块介绍在 VitePress 配置中通过 extends 可以将主题配置合并到 VitePress 配置里，这两步必不可少。

Shiki24 的所有主题配置支持 4 种方式：

  1. provide：在 .vitepress/theme/index.ts 通过 provide 函数注入配置项
  2. frontmatter.s24：在 Markdown 文档的 frontmatter 配置
  3. frontmatter：在 Markdown 文档的 frontmatter 配置
  4. config：在 .vitepress/config.mts 配置

警告

函数式和 Node 环境的配置项无法在 frontmatter 中配置。

优先级依次从高到低排列，如 frontmatter 的配置会覆盖 config 的配置，因此您可以在 config 全局配置，然后在部分 Markdown 文档的 frontmatter 进行局部配置覆盖。

frontmatter.s24 和 frontmatter 配置的区别

  • frontmatter.s24 建议在首页 index.md 配置，目的是为防止和 VitePress 的冲突，而文章页建议使用 frontmatter 配置。
  • 如果部分配置项与第三方插件的配置有冲突，也可以使用 frontmatter.s24 配置。

举个例子：

ts
// .vitepress/theme/index.ts
import Shiki24, { shiki24ConfigContext } from "shiki24";
import "shiki24/index.css";
import { defineComponent, h, provide } from "vue";

export default {
  extends: Shiki24,
  Layout: defineComponent({
    name: "Shiki24Provider",
    setup() {
      provide(shiki24ConfigContext, { author: { name: "come24" } });
      return () => h(Shiki24.Layout);
    },
  }),
};
yaml
---
s24:
  author:
    name: come24
---
yaml
---
author:
  name: come24
---
ts
// .vitepress/config.mts
import { defineConfig } from "vitepress";
import { defineShiki24Config } from "shiki24/config";

const Shiki24Config = defineShiki24Config({
  author: {
    name: "come24",
  },
});

export default defineConfig({
  extends: Shiki24Config,
});

Shiki24 的所有主题配置请阅读 Types 文件。

侧边栏的主题配置专题已经按照模块进行划分，如：

  • 全局配置讲述对全局生效的配置说明
  • Banner 配置讲述对博客风格首页 Banner 模块配置
  • 文章列表配置讲述对博客风格首页的文章列表模块配置
  • ...

接下来请在侧边栏选择自己要配置的模块文章进行阅读。

提示

如果您不想通过多个文章来了解一堆配置项，您可以直接看 配置模板，该文件内容涵盖 Shiki24 95% 的配置项介绍，您可以根据需要复制到 .vitepress/Shiki24Config.mts 文件中，进行配置。

最近更新