定制外观 on OINK

字体预设

Mon, 01 Jan 0001 00:00:00 +0000

OINK 把字体选择收敛到七个语义化 CSS 自定义属性之后。站点覆盖这些角色即可换字体，不需要知道主题内部用了哪些选择器。

整套机制由 Hugo 在构建期编译进同一份静态样式表：不引入 JavaScript、不请求远程字体服务、不需要运行时预设加载器。

params:
  ui:
    typography:
      preset: technical # technical | system

预设	效果
`technical`	默认值。保留 Chakra Petch 与 IBM Plex Mono 的工程观感，字体文件全部本地打包
`system`	展示、元信息、打印与等宽角色改用平台字体栈，不请求任何 OINK 品牌字体

选中的值会输出到 <html> 的 data-td-typography 属性上。无效取值直接让构建失败，而不是静默改变站点外观。

system

预设下，OINK 的品牌字体文件仍然是主题的静态资源，只是浏览器在默认配置下不会去请求它们。

--td-ui-font-family , CSS 属性: 导航、控件与界面外壳。默认继承 --bs-body-font-family。
--td-body-font-family , CSS 属性: 文章与博客正文。默认继承 UI 角色。
--td-heading-font-family , CSS 属性: 内容标题。默认取 $headings-font-family，未设置时回落到正文角色。

Mon, 01 Jan 0001 00:00:00 +0000

OINK 在 Bootstrap 与 Docsy 基础上提供完整的视觉系统，并将字体、图标、样式和浏览器端代码全部本地化。使用方无需重建 Node 依赖树，就能通过设计变量和项目样式完成定制。

Hugo Extended 通过 Hugo Pipes 编译主题 SCSS。项目覆盖项会进入同一个资源包，因此生产构建可以对一份同源样式表完成压缩、指纹和完整性校验。

在站点的 assets/scss/ 目录中覆盖以下文件：

文件	用途
`_variables_project.scss`	在 Bootstrap 与 OINK 默认值之前设置变量
`_variables_project_after_bs.scss`	设置依赖 Bootstrap 定义的变量或映射
`_styles_project.scss`	在主题组件样式之后加载项目选择器

先从最小覆盖项开始：

SCSS

// assets/scss/_variables_project.scss
$primary: #315f8f;
$secondary: #b4762e;

SCSS

// assets/scss/_styles_project.scss
body.td-blog {
  --td-body-font-family: 'Noto Serif', 'Noto Serif SC', serif;
}

普通品牌定制不要直接修改纳管的 Bootstrap、Font Awesome 或本地字体文件。主题更新会覆盖这些改动，也会模糊依赖边界。

稳定的定制层次、字体 preset、语义字体角色与按内容限定作用域的完整说明，参见高级定制。

Mon, 01 Jan 0001 00:00:00 +0000

OINK 提供一套小而清晰的分层定制接口，站点不需要复制组件选择器，也不需要分叉主题。全部样式仍由 Hugo Extended 与 Hugo Pipes 处理，不引入 Node.js、npm、PostCSS、远程字体服务或浏览器端 preset 加载器。

本文记录正式支持的扩展点，以及第一组公开的语义 token：字体系统。颜色模式、代码高亮、导航栏与模板定制示例，参见外观与风格。

优先使用能够表达需求的最高层接口：

层级	扩展点	适用场景
Hugo 配置	`hugo.yaml` 或页面 Front Matter	字体 preset、页面宽度等正式支持的选项
Sass 基础层	`assets/scss/_variables_project.scss`	影响整个样式包的 Docsy 与 Bootstrap 既有变量
Bootstrap 后置 Sass	`assets/scss/_variables_project_after_bs.scss`	少数依赖 Bootstrap 变量或 map 的覆盖项
语义 CSS	`assets/scss/_styles_project.scss`	语义角色、某类内容、某组页面或单个组件
Hugo 模板	`layouts/` 与 Partial hook	CSS 无法表达的结构或 DOM 修改

先尝试配置项或既有 Sass 变量；需要缩小作用域时，再使用语义 CSS 属性。只有找不到合适 token 时才覆盖选择器，只有结构本身必须变化时才覆盖模板。

站点品牌定制不要直接修改主题、Bootstrap、Font Awesome 或主题字体目录中的文件。这些修改难以审计，也会在升级时丢失或产生冲突。

OINK 保持单向依赖：