字体与主题
字体与主题
字体配置
字体配置在 src/data/config/fonts.ts 里。这个文件导出两样东西:fonts 决定站点各处用哪种字体,fontsRegistry 用来登记自带字体以外的字体。
默认字体
// 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 改掉就行:
export const fonts = { display: 'lxgwwenkai' as const, body: 'lxgwwenkai' as const, ui: 'maokenZhuyuanTi' as const, mono: 'monoFonts' as const,};两个中文字体覆盖哪些字,见下文「字体体积优化」。
添加自定义字体
想用自带以外的字体,先在 fontsRegistry 里登记,再在 fonts 里按登记的名字引用。字体可以是放在站点里的本地文件,也可以是在线字体(见下一节「使用 CDN 字体」)。
用本地文件:
- 把 woff2 字体文件放进站点的
public/fonts/:
public/fonts/├── my-font-subset.woff2 ← 子集文件,首屏预加载└── my-font.woff2 ← 完整文件- 在
src/data/config/fonts.ts的fontsRegistry里登记:
// 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', },};- 在同一个文件的
fonts里引用:
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 指定:
// 加在 fontsRegistry 里myFont: { cssName: 'My Font', family: 'sans-serif', path: '/fonts/my-font.woff2', subset: '/fonts/my-font-common.woff2',},只有一个字体文件、没做子集时,把 subset 写成和 path 一样。不写的话,主题会去预加载一个不存在的 -subset 文件,白白多一次请求:
// 加在 fontsRegistry 里myFont: { cssName: 'My Font', family: 'sans-serif', path: '/fonts/my-font.woff2', subset: '/fonts/my-font.woff2',},替换自带字体
fontsRegistry 里的名字和自带字体相同时,以你登记的为准。比如自带霞鹜文楷的子集是按主题示例站的内容做的,想换成按你自己文章生成的字体文件(做法见下文「给自己的字体做子集」),把文件放进 public/fonts/,再用同一个名字登记:
// 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 字段引用,不用本地文件,也不用做子集:
// 加在 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 这类在线字体服务,它的中文字体会按字切成很多小文件,浏览器只下载页面用到的部分
- 不想维护本地字体文件的场景
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 | 用到时才加载 |
加载流程:
- 首屏先加载
subset文件,页面文字立即渲染 - 页面上有子集里没有的字时,浏览器才去加载完整文件;页面上的字子集都有,完整文件就不会下载
- 完整文件加载完之前,这些字先用系统字体(苹方/微软雅黑)显示,加载完自动换上
- 两个文件里都没有的生僻字,一直用系统字体显示
两个文件在页面里登记成两个字体:子集用 cssName,完整文件用「cssName Full」,字体栈里子集在前,缺的字浏览器会顺着字体栈去完整文件里找。
所以用自带中文字体时,你文章里的字只要在 GB2312 一级常用字里,都能用上这个字体;超出这个范围的生僻字会显示成系统字体。
给自己的字体做子集
站点里没有子集化命令。主题仓库里的 pnpm fonts:subset 只用来按示例站的内容给自带字体做子集,不跟着主题包发布。
想按自己的内容做子集(给自己的字体,或者替换自带字体),用 fontTools 的子集工具 pyftsubset 生成 woff2。下面用的 python3 -m fontTools.subset 和 pyftsubset 是同一个工具,在站点根目录运行:
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 里用同名登记(见「替换自带字体」)。
如果写了新文章引入了生僻字(GB2312 一级常用字以外的字),自带字体里没有这些字,会显示为系统默认字体。想让它们也用上同一种字体,按「给自己的字体做子集」用自己的内容生成字体文件,再按「替换自带字体」登记;之后再用到新字,重新生成一次子集文件即可。