MkDocs Material 本地字体配置教程（霞鹜文楷版）

本教程旨在帮助你将下载的 **LXGW WenKai GB Screen** 字体集成到 MkDocs 站点中，并优化加载体验。

## 1. 项目目录结构

确保你的字体文件与 CSS 文件存放在同一目录下，以便使用相对路径引用。根据你的 `tree` 输出，结构如下：

```text
mydoc/
├── mkdocs.yml
└── docs/
    ├── assets/
    │   └── fonts/
    │       ├── extra.css              # 字体定义与应用
    │       ├── LXGWWenKaiGBScreen.ttf  # 备用字体
    │       └── LXGWWenKaiGBScreen.woff2 # 核心推荐字体（体积更小）
    └── stylesheets/
        └── custom.css                 # 其他自定义样式

```

## 2. 编写自定义 CSS (`extra.css`)

在 `docs/assets/fonts/extra.css` 中写入以下配置。

> **核心技巧**：通过设置 `font-display: block`，强制浏览器在字体完全加载前不显示文字，从而**彻底消除**默认字体切换到自定义字体时的“闪烁”感。

```css
/* 1. 定义本地字体 */
@font-face {
    font-family: 'LXGW WenKai GB Screen';
    /* 相对路径指向同目录下的 woff2 文件 */
    src: url('./LXGWWenKaiGBScreen.woff2') format('woff2');         
    font-weight: normal;
    font-style: normal;
    
    /* block 模式：防止字体加载过程中的视觉抖动 */
    font-display: block;
}

/* 2. 应用于 Material 主题变量 */
:root {
    /* 修改正文字体 */
    --md-text-font: 'LXGW WenKai GB Screen', sans-serif;
    /* 修改代码块字体（如果你希望代码也使用文楷） */
    --md-code-font: 'LXGW WenKai GB Screen', monospace;
}

```

## 3. 修改 `mkdocs.yml` 配置

你需要执行两步关键操作：**禁用默认字体** 和 **引入自定义 CSS**。

```yaml
theme:
  name: material
  # 必须禁用默认字体，否则会从 Google Fonts 下载默认字体覆盖你的设置
  font: false

extra_css:
  - stylesheets/custom.css    # 你的其他样式
  - assets/fonts/extra.css     # 字体配置样式

```

## 4. 部署注意事项

* **编码格式**：确保所有 `.css` 和 `.yml` 文件保存为 **UTF-8** 编码，防止在服务器上出现乱码。
* **缓存刷新**：在浏览器预览时，如果字体未生效，请尝试 `Ctrl + F5` 强制刷新，以清除旧的 CSS 缓存。
* **WOFF2 优势**：优先使用 `woff2` 格式，它比 `ttf` 体积更小，能显著提升页面打开速度。

---

### 验证与调试

启动服务后，你可以通过浏览器开发者工具（`F12`）的 **Network** 选项卡查看 `LXGWWenKaiGBScreen.woff2` 是否成功加载。如果状态码为 `200` 且没有 `404` 报错，则说明配置成功。