输入关键词,开始搜索

↑↓ 选择↵ 打开esc 关闭
沉浸

字体与主题

字体与主题

字体配置

字体配置在 src/data/config/fonts.ts 里。这个文件导出两样东西:fonts 决定站点各处用哪种字体,fontsRegistry 用来登记自带字体以外的字体。

默认字体

TypeScript
// src/data/config/fonts.tsexport const fonts = {    display: 'maokenZhuyuanTi' as const,    body: 'lxgwwenkai' as const,    ui: 'maokenZhuyuanTi' as const,    mono: 'monoFonts' as const,};

自带字体

主题自带下面几种字体,字体文件跟着主题包一起安装,站点里不用放任何字体文件,在 fonts 里写名字就能用:

名字 字体 说明
lxgwwenkai 霞鹜文楷 中文,已子集化
maokenZhuyuanTi 猫啃珠圆体 中文,已子集化
inter Inter 西文
monoFonts 系统等宽字体 用系统自带的等宽字体,不下载字体文件

比如想让标题也用霞鹜文楷,把 display 改掉就行:

TypeScript
export const fonts = {    display: 'lxgwwenkai' as const,    body: 'lxgwwenkai' as const,    ui: 'maokenZhuyuanTi' as const,    mono: 'monoFonts' as const,};

两个中文字体覆盖哪些字,见下文「字体体积优化」。

添加自定义字体

想用自带以外的字体,先在 fontsRegistry 里登记,再在 fonts 里按登记的名字引用。字体可以是放在站点里的本地文件,也可以是在线字体(见下一节「使用 CDN 字体」)。

用本地文件:

  1. 把 woff2 字体文件放进站点的 public/fonts/:
public/fonts/├── my-font-subset.woff2   ← 子集文件,首屏预加载└── my-font.woff2          ← 完整文件
  1. 在 src/data/config/fonts.ts 的 fontsRegistry 里登记:
TypeScript
// src/data/config/fonts.tsexport const fontsRegistry: Record<string, { cssName: string; family: string; path?: string; subset?: string; cdn?: string; format?: string }> = {    myFont: {        cssName: 'My Font',        family: 'sans-serif',        path: '/fonts/my-font.woff2',        format: 'woff2',    },};
  1. 在同一个文件的 fonts 里引用:
TypeScript
export const fonts = {    display: 'myFont' as const,    body: 'myFont' as const,    ui: 'maokenZhuyuanTi' as const,    mono: 'monoFonts' as const,};

登记时能写的字段:

字段 含义
cssName 字体在 CSS 里的名字。本地文件可以自己起;在线字体要和它的 CSS 里声明的名字一致
family 这个字体缺字或没加载出来时用的后备字体,比如 sans-serif、serif
path 本地完整文件的地址。public/fonts/x.woff2 写成 /fonts/x.woff2
subset 子集文件的地址,不写时默认是 path 同目录的 <文件名>-subset.woff2
cdn 在线字体的 CSS 地址,见下一节
format 文件格式,不写时是 woff2

子集文件:主题会预加载一个子集文件,让首屏文字尽快显示。上面的例子没写 subset,主题就去找 /fonts/my-font-subset.woff2。文件名不是这个规则时,用 subset 指定:

TypeScript
// 加在 fontsRegistry 里myFont: {    cssName: 'My Font',    family: 'sans-serif',    path: '/fonts/my-font.woff2',    subset: '/fonts/my-font-common.woff2',},

只有一个字体文件、没做子集时,把 subset 写成和 path 一样。不写的话,主题会去预加载一个不存在的 -subset 文件,白白多一次请求:

TypeScript
// 加在 fontsRegistry 里myFont: {    cssName: 'My Font',    family: 'sans-serif',    path: '/fonts/my-font.woff2',    subset: '/fonts/my-font.woff2',},

替换自带字体

fontsRegistry 里的名字和自带字体相同时,以你登记的为准。比如自带霞鹜文楷的子集是按主题示例站的内容做的,想换成按你自己文章生成的字体文件(做法见下文「给自己的字体做子集」),把文件放进 public/fonts/,再用同一个名字登记:

TypeScript
// src/data/config/fonts.tsexport const fontsRegistry: Record<string, { cssName: string; family: string; path?: string; subset?: string; cdn?: string; format?: string }> = {    lxgwwenkai: {        cssName: 'LXGW WenKai',        family: 'sans-serif',        path: '/fonts/LXGWWenKai-Regular.woff2',        format: 'woff2',    },};

子集文件按上面的规则默认是 /fonts/LXGWWenKai-Regular-subset.woff2。fonts 里原来写的 'lxgwwenkai' 不用改,用的就是你的文件了。

使用 CDN 字体(免子集化)

如果字体有现成的在线地址(如 Google Fonts),可以直接通过 cdn 字段引用,不用本地文件,也不用做子集:

TypeScript
// 加在 fontsRegistry 里notoSerif: {    cssName: 'Noto Serif SC',    family: 'serif',    cdn: 'https://fonts.googleapis.com/css2?family=Noto+Serif+SC&display=swap',},

cdn 填的是字体的 CSS 地址,不是字体文件地址。主题会在页面里用 <link rel="stylesheet"> 引入这份 CSS,字体由它里面的 @font-face 加载,所以 cssName 要和这份 CSS 里声明的字体名一致。适合:

  • 已经有 CDN 分发的商用字体
  • Google Fonts 这类在线字体服务,它的中文字体会按字切成很多小文件,浏览器只下载页面用到的部分
  • 不想维护本地字体文件的场景
Tip

path 和 cdn 二选一即可,两个都写时按 path 处理。path 走本地文件(预加载子集文件),cdn 走在线 CSS(不经过子集化)。

单篇文章自定义字体

在文章信息头中覆盖字体,名字可以是自带字体,也可以是 fontsRegistry 里登记的字体:

---
title: 特殊排版文章
fonts:
  display: 'maokenZhuyuanTi'
  body: 'lxgwwenkai'
---

主题切换

Vergil 支持暗色/亮色模式切换,点击网站右上角的太阳/月亮图标即可切换。

配色方案

经典皮肤自带 10 套配色方案(A–I 和 K),在主题切换面板中选择:

  • 点击右上角主题图标
  • 选择喜欢的配色方案
  • 系统会自动保存你的选择

暗色模式

在配色方案旁边有单独的暗色/亮色切换开关,独立于配色方案。

默认主题

如果你想设置网站默认的配色方案和暗色模式,可以在 src/data/site-config.ts 中配置(高级用法)。


字体体积优化

中文字体文件通常很大(单文件 5-30MB),直接加载会严重影响首屏速度。Vergil 用子集化加双文件加载来解决这个问题,自带的两个中文字体已经由主题处理好了。

为什么需要子集化

中文字体包含成千上万个字形(矢量图形),但你的网站实际用到的可能只有几百个。子集化就是只保留实际需要的字形,删除没用到的,从而大幅减小文件体积。

双文件加载策略

每种本地字体用两个文件。自带的两个中文字体是这样分的:

文件 内容 大小 加载方式
字体名-subset.woff2 主题示例站用到的字 + ASCII ~250-300KB 立即加载(preload)
字体名.woff2 子集 + GB2312 一级常用字(3755 字) ~650-900KB 用到时才加载

加载流程:

  1. 首屏先加载 subset 文件,页面文字立即渲染
  2. 页面上有子集里没有的字时,浏览器才去加载完整文件;页面上的字子集都有,完整文件就不会下载
  3. 完整文件加载完之前,这些字先用系统字体(苹方/微软雅黑)显示,加载完自动换上
  4. 两个文件里都没有的生僻字,一直用系统字体显示

两个文件在页面里登记成两个字体:子集用 cssName,完整文件用「cssName Full」,字体栈里子集在前,缺的字浏览器会顺着字体栈去完整文件里找。

所以用自带中文字体时,你文章里的字只要在 GB2312 一级常用字里,都能用上这个字体;超出这个范围的生僻字会显示成系统字体。

给自己的字体做子集

站点里没有子集化命令。主题仓库里的 pnpm fonts:subset 只用来按示例站的内容给自带字体做子集,不跟着主题包发布。

想按自己的内容做子集(给自己的字体,或者替换自带字体),用 fontTools 的子集工具 pyftsubset 生成 woff2。下面用的 python3 -m fontTools.subset 和 pyftsubset 是同一个工具,在站点根目录运行:

Bash
pip3 install fonttools brotli # 收集站点内容和配置里用到的字find src/content src/data \( -name '*.md*' -o -name '*.ts' \) -exec cat {} + > chars.txt # 子集文件:用到的字 + ASCIIpython3 -m fontTools.subset MyFont.ttf --text-file=chars.txt --unicodes=U+0020-007E --flavor=woff2 --output-file=public/fonts/my-font-subset.woff2 # 完整文件:保留全部字python3 -m fontTools.subset MyFont.ttf --unicodes='*' --flavor=woff2 --output-file=public/fonts/my-font.woff2

完整文件保留全部字会比较大,也可以像主题那样只保留常用字。生成后按「添加自定义字体」或「替换自带字体」登记。chars.txt 和字体源文件(.ttf)只是生成用的,不用提交。

字体文件目录说明

node_modules/@vergil-astro/theme/src/fonts/   ← 自带字体,随主题包安装,构建时自动打包├── LXGWWenKai-Regular-subset.woff2├── LXGWWenKai-Regular.woff2├── maoken-zhuyuan-ti-subset.woff2└── maoken-zhuyuan-ti.woff2public/fonts/                                 ← 你自己的字体,登记了本地字体时才需要,进入 dist├── my-font-subset.woff2└── my-font.woff2

不要在 node_modules 里替换自带字体,升级或重装主题就会被覆盖。要换就在 fontsRegistry 里用同名登记(见「替换自带字体」)。

Tip

如果写了新文章引入了生僻字(GB2312 一级常用字以外的字),自带字体里没有这些字,会显示为系统默认字体。想让它们也用上同一种字体,按「给自己的字体做子集」用自己的内容生成字体文件,再按「替换自带字体」登记;之后再用到新字,重新生成一次子集文件即可。

未知标题
00:00
00:00
播放列表