Nav Display Spec · v1.0.1
站点目录显示规范 v1.0.1
mkdocs.yml 配置约定 · features / nav / 资源加载 / 徽章规则
站点目录显示规范 v1.0.1
本文档定位
- 角色:站点级配置约定 —— 把"目录怎么展示给用户"这件事固化成 mkdocs.yml 可执行规则
- 管辖范围:
mkdocs.yml主配置文件 +overrides/模板覆盖 +docs/assets/静态资源加载顺序 - 不管辖:目录文件夹的物理结构(见 folder-structure-spec.md);MD 文件内格式(见 md-writing-spec.md v2.0)
- 下游受众:文档管理员智能体在执行 P0 阶段时,按本文档配置 mkdocs.yml
v1.0.1 版本要点(2026-05-11 · 含 Stripe 布局补丁)
- 首版发布 · 涵盖 features / nav / extra_css/js / theme.palette / status 徽章 / KaTeX 动态加载 7 大维度
- 与 IA v3(数字前缀目录)对齐,作为「D 系列 → 数字前缀」迁移完成后的目标态配置
- 引用 format-spec-changelog.md 决议 4 / 7 / 8 的视觉规则
- ⭐ v1.0.1 补丁(2026-05-11):新增 §3「Stripe 三栏布局规范」专章 — 落地 第一组导航方案决议:Demo 1 · Stripe 风格(深色侧栏 260px / 主区 720px / 右 TOC 220px),含完整 CSS 变量 + Material 主题集成方式 + 与产品 6 色协调约定
1. theme.features 标准配置
mkdocs.yml 中 theme.features 字段必须完整包含以下条目(顺序无关,但不得遗漏):
theme:
name: material
custom_dir: overrides
palette:
# 见 §6
features:
# === 导航类 · 必选 ===
- navigation.tabs # 顶部一级 tab(对应 IA v3 9 个一级目录)
- navigation.tabs.sticky # tab 悬停时固定顶部
- navigation.sections # 侧栏二级目录显示为分组
- navigation.expand # 默认展开当前路径下所有节点(详见 §2.1)
- navigation.indexes # 一级目录用 index.md 作为入口页(详见 §4)
- navigation.top # 「回到顶部」按钮
- navigation.tracking # URL 自动同步当前章节锚点
- navigation.footer # 上一页 / 下一页 footer 导航
# === 搜索类 · 必选 ===
- search.highlight # 搜索结果高亮命中词
- search.share # 分享搜索链接
- search.suggest # 输入时实时建议
# === 内容类 · 必选 ===
- content.code.copy # 代码块右上角复制按钮
- content.code.annotate # 代码块行内注解(1)(2) 圆圈
- content.tabs.link # Tabs 切换时同步全站(同一 Tab 名联动)
- content.tooltips # 悬停提示(abbr 缩写)
# === 标题类 · 推荐 ===
- toc.follow # 滚动时右侧 TOC 自动跟随高亮
# 注:不启用 toc.integrate(那会把 TOC 合并到左侧 nav,我们用右侧独立 TOC)
禁用清单(不得开启):
- ❌ navigation.instant — 与 Mermaid + KaTeX 动态加载冲突,会导致放大按钮失效
- ❌ navigation.prune — 会裁剪非当前路径的 nav,与「展开 D2 全部产品」需求冲突
- ❌ header.autohide — 算法部读者需要顶部 tab 常驻
2. nav 展开 / 折叠规则
2.1 默认展开策略
navigation.expand 启用后,当前页面所在路径的所有父级章节自动展开。
用户进入站点时的初始状态:
- 一级目录(9 个)全部以 tab 形式呈现在顶部(navigation.tabs)
- 当用户进入 00-home/ 时,左侧 nav 不显示(首页是 L1A,无 sidebar)
- 进入其他一级目录时,左侧 nav 显示该目录全部二级章节(默认折叠子级)
2.2 nav 顺序约定
mkdocs.yml: nav 字段必须严格按 IA v3 顺序列出 9 个一级目录:
nav:
- 首页: index.md # 00-home(站点根)
# ═══════════ 战略层 ═══════════
- 01 战略: 01-strategy/index.md # 一级目录用 index.md(navigation.indexes)
# ═══════════ 产品层 · 主战场 ═══════════
- 02 产品: # 一级目录可不带 emoji
- 概览: 02-products/index.md
- P1 XiStudio:
- 概览: 02-products/P1-xistudio/index.md
- 业务: 02-products/P1-xistudio/business/index.md
- 架构: 02-products/P1-xistudio/architecture/index.md
# ... 13 个稳态文档 + modules/ + _dev/
# ═══════════ 平台层 ═══════════
- 03 平台: 03-platform/index.md
# ═══════════ 部门规范 ═══════════
- 04 部门: 04-departments/index.md
# ═══════════ 跨部门标准 ═══════════
- 05 标准:
- 概览: 05-standards/index.md
- MD 写作规范: 05-standards/md-writing-spec.md
- 品牌色彩系统: 05-standards/brand-color-system.md
- 目录显示规范: 05-standards/nav-display-spec.md # 本文件
- 目录结构规范: 05-standards/folder-structure-spec.md
- 格式变更日志: 05-standards/format-spec-changelog.md
- 文档编号: 05-standards/doc-numbering.md
- PR 检查清单: 05-standards/checklist.md
- 跨部门交付索引: 05-standards/release-to-other-depts.md
- 迁移计划 2026Q2: 05-standards/migration-plan-2026Q2.md
# ═══════════ 客户专区 ═══════════
- 06 客户: 06-customer/index.md
# ═══════════ 全局工程 ═══════════
- 07 工程: 07-engineering/index.md
# 注:99-archive 不在主 nav,仅在 footer 加底部小入口
2.3 emoji 使用约定
| 位置 | 是否用 emoji | 规则 |
|---|---|---|
| 一级目录(主 nav tab) | 不用 | 文字简洁:「02 产品」而非「📦 02 产品」 |
| 二级章节(P1 XiStudio 等产品) | 可选 | 用了就所有产品都用,不混用;推荐统一不用 |
| 三级以下章节 | 不用 | 避免 emoji 噪声 |
| 标题 H1-H6 | 不用 | 已在 md-writing-spec.md §4 禁用 |
| Hero 标语 | 可用 | hero_tagline / hero_meta 中可用 emoji 增强情绪 |
3. Stripe 三栏布局规范(v1.0.1 新增 ⭐)
决议来源:format-spec-changelog.md 决议 10(第一组早期导航方案 3 选 1 · 已选 Demo 1 Stripe 风格) 视觉源文件:
nav-demo/demo-1-stripe-style.html(已用户确认 ✓) 参考来源:stripe.com/docs+linear.app/docs
3.1 总体布局
三栏 grid 布局(浏览器视窗宽度 ≥ 900px 时启用):
┌─────────────────────────────────────────────────────────────┐
│ Banner 28px 高(紫色渐变,可选) │
├──────────────┬─────────────────────────────────┬────────────┤
│ │ │ │
│ Sidebar │ Main Content │ TOC │
│ 260px │ 1fr (主区 max-width 720px) │ 220px │
│ 深海军蓝 │ 白底浅灰文字 │ 右侧 nav │
│ │ │ │
└──────────────┴─────────────────────────────────┴────────────┘
核心 CSS(加到 xiyin-extra.css):
body.xy-stripe-layout {
display: grid;
grid-template-columns: 260px 1fr 220px;
height: 100vh;
overflow: hidden;
padding-top: 28px; /* banner 高度 · 不用 banner 时设为 0 */
}
@media (max-width: 900px) {
body.xy-stripe-layout {
grid-template-columns: 1fr; /* 移动端单栏 */
}
}
3.2 完整 CSS 变量定义
11 个 Stripe 布局专用变量(加到 xiyin-brand.css 末尾):
:root {
/* === Stripe 三栏布局色板(v1.0.1 新增) === */
--xy-sidebar-bg: #0a2540; /* 侧栏深海军蓝 */
--xy-sidebar-fg: #adbdcc; /* 侧栏默认文字 */
--xy-sidebar-fg-active: #ffffff; /* 侧栏当前项文字 */
--xy-sidebar-fg-dim: #6b7c93; /* 侧栏次级文字(L3 / 分组标题) */
--xy-sidebar-hover: #ffffff10; /* hover 半透明 */
--xy-stripe-accent: var(--yin); /* 当前项左边线 — 用玫瑰金接管 Stripe 紫 #635bff */
--xy-main-bg: var(--paper); /* 主区底 — 用米纸 */
--xy-main-fg: #0a2540; /* 主区主文字 */
--xy-main-fg-dim: #425466; /* 主区次级文字 */
--xy-stripe-border: var(--line); /* 分隔线 — 用项目线条色 */
--xy-stripe-code-bg: #f6f9fc; /* 行内代码底 */
}
⚠️ 关键决策:Stripe demo 原色
#635bff紫被替换为项目玫瑰金var(--yin) #D4A574接管 — 保持 Xiyin 三色法典纯净,禁止引入 Stripe 紫作为第 5 色。
3.3 Sidebar(侧栏 260px)详细规范
| 部位 | 字号 | 颜色 | 内边距 |
|---|---|---|---|
.sb-logo(品牌名) |
16px / 700 | #fff |
0 24px 20px |
.sb-logo-mark(28×28 角标) |
14px / 700 | 三色法典渐变(--gradient-trinity) |
border-radius: 8px |
.sb-search(搜索框) |
13px | 输入字 #fff / 占位 --xy-sidebar-fg-dim |
8px 12px 8px 32px |
.sb-group-title(分组标题) |
11px / 600 / uppercase / letter-spacing: 0.8px |
--xy-sidebar-fg-dim |
10px 24px 6px |
.sb-item.lvl-1(一级目录) |
13px / 500 | #cdd5df |
padding-left: 24px |
.sb-item.lvl-2(二级目录) |
12.5px | --xy-sidebar-fg |
padding-left: 40px |
.sb-item.lvl-3(三级目录) |
12.5px | --xy-sidebar-fg-dim |
padding-left: 56px |
.sb-item.active(当前项) |
(继承层级) | --xy-sidebar-fg-active |
背景: #ffffff08 |
.sb-item.active::before(色条) |
— | --xy-stripe-accent 玫瑰金 |
2px 宽 / 100% 高 / 左对齐 |
3.4 Main Content(主区)详细规范
| 元素 | 字号 / 字重 | 颜色 | 间距 |
|---|---|---|---|
.main-inner 容器 |
— | — | max-width: 720px 严格 |
.main 内边距 |
— | — | padding: 48px 64px |
.crumb(面包屑) |
12px | --xy-main-fg-dim |
margin-bottom: 16px |
h1(页面标题) |
32px / 700 / letter-spacing: -0.4px |
--xy-main-fg |
margin-bottom: 12px |
.lead(副标题) |
17px / 1.6 | --xy-main-fg-dim |
margin-bottom: 32px |
h2 |
22px / 600 / letter-spacing: -0.2px |
--xy-main-fg |
margin: 36px 0 14px |
h3 |
16px / 600 | --xy-main-fg |
margin: 24px 0 8px |
p, li |
15px / 1.7 | #3c4257 |
margin-bottom: 12px |
行内 code |
13px / JetBrains Mono |
--xy-main-fg 文字 + --xy-stripe-code-bg 底 |
padding: 2px 6px / border-radius: 4px |
pre(代码块) |
13px | (同上) | border: 1px solid var(--xy-stripe-border) / border-radius: 8px / padding: 16px |
a(链接) |
(继承) | --xy-stripe-accent 玫瑰金 |
hover 加 text-decoration: underline |
.callout |
14px | border-left: 3px solid --xy-stripe-accent |
padding: 14px 18px / border-radius: 0 6px 6px 0 / 背景 rgba(玫瑰金, 0.05) |
3.5 Right TOC(右侧目录 220px)详细规范
| 部位 | 字号 / 字重 | 颜色 | 间距 |
|---|---|---|---|
.toc 容器 |
13px | — | border-left: 1px solid var(--xy-stripe-border) / padding: 48px 24px |
.toc-title |
11px / 600 / uppercase / letter-spacing: 0.8px |
--xy-main-fg-dim |
margin-bottom: 12px |
.toc a(H2) |
13px | --xy-main-fg-dim |
padding: 4px 0 / padding-left: 10px / margin-left: -10px / border-left: 2px solid transparent |
.toc a.toc-h3(H3) |
12.5px | (同上) | padding-left: 24px |
.toc a:hover |
— | --xy-stripe-accent 玫瑰金 |
— |
.toc a.active |
— | --xy-stripe-accent 玫瑰金 |
border-left-color: --xy-stripe-accent |
3.6 Banner(顶部条带 · 可选)
.xy-banner {
position: fixed; top: 0; left: 0; right: 0; z-index: 100;
height: 28px;
background: var(--gradient-trinity); /* 三色法典渐变(替代 Stripe 紫蓝渐变) */
color: #fff; text-align: center; padding: 6px 16px;
font-size: 12px; font-weight: 500; letter-spacing: 0.3px;
}
.xy-banner a { color: #fff; text-decoration: underline; }
3.7 Material 主题集成策略
mkdocs-material 默认是双栏(左 nav + 主区,无独立右 TOC)。落地 Stripe 三栏需要:
| 集成点 | 实现方式 | 难度 |
|---|---|---|
| 左栏宽度 260px | xiyin-extra.css 覆盖 .md-sidebar--primary { width: 260px } |
⭐ |
| 左栏深色 | xiyin-extra.css 覆盖 .md-sidebar--primary { background: var(--xy-sidebar-bg) } + 文字色 |
⭐ |
| 右 TOC 独立 220px | 用 Material 自带的 .md-sidebar--secondary(已是右 TOC),覆盖宽度为 220px + 边框 |
⭐⭐ |
| 主区 max-width 720px | 覆盖 .md-content { max-width: 720px; padding: 48px 64px } |
⭐ |
| 当前项色条 | 覆盖 .md-nav__link--active::before 注入 2px 玫瑰金条 |
⭐⭐ |
| 侧栏字号 13px / 12.5px / 11px | 覆盖 .md-nav__link / .md-nav--secondary .md-nav__link / .md-nav__title 的 font-size |
⭐⭐ |
| 顶部 Banner(可选) | 用 overrides/main.html 在 {% block announce %} 注入 |
⭐⭐ |
xiyin-extra.css 落地骨架(P0 阶段任务):
/* === Stripe 三栏布局接管 Material(v1.0.1) === */
/* 左 sidebar 宽度 260px + 深色 */
.md-sidebar--primary {
width: 260px !important;
background: var(--xy-sidebar-bg);
color: var(--xy-sidebar-fg);
}
.md-sidebar--primary .md-nav__link {
color: var(--xy-sidebar-fg);
font-size: 13px;
}
.md-sidebar--primary .md-nav__link--active {
color: var(--xy-sidebar-fg-active);
position: relative;
}
.md-sidebar--primary .md-nav__link--active::before {
content: ''; position: absolute; left: 0; top: 0; bottom: 0;
width: 2px; background: var(--xy-stripe-accent);
}
.md-sidebar--primary .md-nav__title {
font-size: 11px;
font-weight: 600;
text-transform: uppercase;
letter-spacing: 0.8px;
color: var(--xy-sidebar-fg-dim);
}
/* 右 TOC 220px + 边框 */
.md-sidebar--secondary {
width: 220px !important;
border-left: 1px solid var(--xy-stripe-border);
padding: 48px 24px;
}
/* 主区 max-width 720px */
.md-content {
max-width: 720px;
padding: 48px 64px;
}
.md-content__inner { max-width: 720px; }
/* 主区字号 / 行高(覆盖 Material 默认) */
.md-typeset h1 { font-size: 32px; font-weight: 700; letter-spacing: -0.4px; }
.md-typeset h2 { font-size: 22px; font-weight: 600; letter-spacing: -0.2px; margin: 36px 0 14px; }
.md-typeset h3 { font-size: 16px; font-weight: 600; margin: 24px 0 8px; }
.md-typeset p, .md-typeset li { font-size: 15px; line-height: 1.7; }
3.8 与 9 条视觉决议的协调
Stripe 布局是站点骨架,9 条视觉决议是内容组件,二者正交不冲突:
| 维度 | Stripe 布局负责 | 9 条决议负责 |
|---|---|---|
| 三栏 grid / sidebar / main / TOC | ✅ | — |
| 字号 / 字距 / 行高 / 颜色变量 | ✅(11 个 CSS 变量) | — |
| Admonition 6 组语义配色 | — | ✅(决议 3) |
9 个视觉组件(.xy-quote / .xy-glossary / ...) |
— | ✅(决议 ½/6/⅞/9) |
| Tabs 激活态 / Mermaid 放大 | — | ✅(决议 4 / 7) |
色彩协调约定:
- ✅ Stripe 主色 #635bff → 替换为玫瑰金 var(--yin)(三色法典之一)
- ✅ Stripe 蓝渐变 → 替换为三色法典渐变 var(--gradient-trinity)
- ✅ 侧栏深海军蓝 #0a2540 与项目「夜蓝堆栈 deep #0B1C2E」几乎一致(色差 < 5%),保留 #0a2540 作为侧栏专用变量
- ❌ 禁止在 Stripe 布局任何位置使用原 Stripe 紫 #635bff / 蓝 #00d4ff
3.9 落地验收清单(P0 阶段)
-
xiyin-brand.css含 11 个--xy-sidebar-* / --xy-main-* / --xy-stripe-*变量 -
xiyin-extra.css含 §3.7 完整接管 CSS(覆盖 Material 默认双栏) - 关键验收:
mkdocs serve打开任一文档页,视觉应等同于nav-demo/demo-1-stripe-style.html(三栏宽度 / 深色侧栏 / 当前项玫瑰金色条 / 右 TOC 边线 / 主区 720px 居中) - 侧栏字号严格 13/12.5/11px(L1/L2/L3-或group)
- 当前项 2px 玫瑰金色条无遗漏
- 移动端(<900px)单栏退化正常
- 0 残留 Stripe 紫
#635bff/ 蓝#00d4ff(全文 grep 验证)
4. extra_javascript / extra_css 加载顺序
4.1 加载顺序约定(P0 阶段固化)
extra_css:
# === 主题层(从底到上) ===
- assets/stylesheets/xiyin-brand.css # 1. CSS 变量总定义(最先)
- assets/stylesheets/xiyin-extra.css # 2. 组件皮肤(含 9 条视觉组件)
- assets/stylesheets/xiyin-patch.css # 3. 补丁层(Admonition 6 组配色映射 + Pygments)
# === KaTeX(可选 · 仅当任一文档 frontmatter 有 katex: true 时按需加载) ===
- https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css
extra_javascript:
# === 第三方库(从底到上) ===
- https://cdn.jsdelivr.net/npm/mermaid@10.6.1/dist/mermaid.min.js
- https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js
- https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js
# === 主题增强 JS(顺序敏感!) ===
- assets/javascripts/xiyin-stars.js # 1. Hero 星空动画
- assets/javascripts/xiyin-comets.js # 2. Hero 彗星动画
- assets/javascripts/xiyin-mermaid.js # 3. Mermaid classDef 注入(必须在 mermaid.min.js 之后)
- assets/javascripts/xiyin-mermaid-zoom.js # 4. Mermaid 放大按钮(必须在 xiyin-mermaid.js 之后)
- assets/javascripts/xiyin-katex.js # 5. KaTeX auto-render(条件加载,见 §3.2)
- assets/javascripts/xiyin-wrap.js # 6. 表格 .xy-tbox 包裹 + Tab 激活态
- assets/javascripts/xiyin-toc-merge.js # 7. TOC 合并(最后)
⚠️ 加载顺序违反会导致:Mermaid 放大按钮失效 / classDef 不生效 / Tab 三角箭头丢失。
4.2 KaTeX 按 frontmatter 动态加载方案
决议:仅当文档 frontmatter 含
katex: true时,才在该页面加载 KaTeX CDN(避免全站 +280KB 包体)
实现方式(由 overrides/main.html Jinja2 模板控制):
{% extends "base.html" %}
{% block extrahead %}
{{ super() }}
{%- if page and page.meta and page.meta.katex %}
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css">
{%- endif %}
{% endblock %}
{% block libs %}
{{ super() }}
{%- if page and page.meta and page.meta.katex %}
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js"></script>
<script defer src="{{ 'assets/javascripts/xiyin-katex.js' | url }}"></script>
{%- endif %}
{% endblock %}
作者 frontmatter 示例:
好处: - ✅ 90% 文档不需要 KaTeX,不加载 → 站点更快 - ✅ 算法详解类文档显式声明,加载完整 LaTeX 渲染 - ✅ 与 md-writing-spec.md §15.2 的「双轨公式」约定对齐
5. nav indexes · 一级目录的 index.md 约定
5.1 必须的 index.md 文件清单
navigation.indexes 启用后,每个一级目录必须有一个 index.md 作为该目录的「门面页」:
| 一级目录 | index.md 路径 | 角色 |
|---|---|---|
00-home/ |
docs/index.md |
站点首页(L1A · 含 Hero + 8 张大卡片导览) |
01-strategy/ |
docs/01-strategy/index.md |
战略层概览(L1B · 列出战略 / 品牌 / 制度 / 融资入口) |
02-products/ |
docs/02-products/index.md |
产品矩阵 V2.0(L1B · 含 Mermaid 6 层架构图) |
03-platform/ |
docs/03-platform/index.md |
平台层概览(L1B) |
04-departments/ |
docs/04-departments/index.md |
各部门入口(L2) |
05-standards/ |
docs/05-standards/index.md |
跨部门标准索引(L1B · 列出本目录全部规范文档) |
06-customer/ |
docs/06-customer/index.md |
客户专区欢迎页(L1B) |
07-engineering/ |
docs/07-engineering/index.md |
全局工程过程入口(L2) |
99-archive/ |
docs/99-archive/index.md |
归档目录(L3 · 极简) |
5.2 index.md vs README.md 选择规则
统一用
index.md(P0 阶段强制),原因: - mkdocs materialnavigation.indexes只识别index.md,不识别README.md- 旧目录散落的README.md在 P1 阶段批量重命名为index.md(详见 migration-plan-2026Q2.md)
例外:产品 _dev/ 子目录可保留 README.md(开发过程文档,不进 nav)。
5.3 index.md 标准模板
---
title: 【目录中文名】
description: 【一句话说明】
doc_id: INDEX-【目录代号】-001
level: l1b
hero_show: true
hero_label: 【目录英文名】 · v1.0
hero_title: 【目录中文名】
hero_sub: 【副标题】
hero_meta: 包含 N 篇文档 · 最后更新:YYYY-MM-DD
category: spec
status: published
audience: all
owner: 【目录所有人】
last_review: YYYY-MM-DD
version: 1.0
---
# 【目录中文名】
!!! abstract "本目录角色"
【一段话说清本目录在 IA v3 中的定位】
## 文档索引
- [子目录 1](sub-dir-1/index.md)
- [子目录 2](sub-dir-2/index.md)
- ...
6. status 徽章渲染规则
frontmatter 中的 status 字段在站点上自动渲染为徽章,由 overrides/main.html Jinja2 模板控制。
6.1 4 种 status 值与渲染
| status | 徽章颜色(CSS 变量) | 显示位置 | 何时使用 |
|---|---|---|---|
draft |
--status-wip 米黄 #C9A33F |
文档标题右侧 | 草稿、未审阅 |
review |
--status-plan 灰 #7A8A9B |
文档标题右侧 | 评审中 |
published |
--status-done 翠绿 #5DA88E |
文档标题右侧 | 已发布(默认 hide,文档量大时减少噪声) |
deprecated |
--status-archived 棕灰 #A89B8A |
文档标题左侧 + 顶部横幅警告 | 已废弃,链接保留 |
6.2 实现方式(overrides/main.html)
{% block content %}
{%- if page and page.meta and page.meta.status %}
{%- if page.meta.status == 'deprecated' %}
<div class="xy-status-banner xy-status-deprecated">
⚠️ 本文档已被标记为 <strong>已废弃</strong>。
{%- if page.meta.legacy_doc_id %}
请改用新版本:<code>{{ page.meta.legacy_doc_id }}</code>。
{%- endif %}
</div>
{%- endif %}
{%- if page.meta.status != 'published' %}
<span class="xy-status-badge xy-status-{{ page.meta.status }}">
{{ page.meta.status | upper }}
</span>
{%- endif %}
{%- endif %}
{{ super() }}
{% endblock %}
6.3 配套 CSS(加到 xiyin-extra.css)
.xy-status-badge {
display: inline-block;
padding: 0.15rem 0.6rem;
font-size: 0.75rem;
font-weight: 600;
border-radius: 3px;
margin-left: 0.5rem;
vertical-align: middle;
}
.xy-status-draft { background: var(--status-wip); color: white; }
.xy-status-review { background: var(--status-plan); color: white; }
.xy-status-deprecated { background: var(--status-archived); color: white; }
.xy-status-banner {
padding: 0.75rem 1rem;
margin: 0 0 1.5rem;
border-left: 4px solid;
border-radius: 4px;
font-size: 0.9rem;
}
.xy-status-deprecated {
background: rgba(168, 155, 138, 0.1);
border-left-color: var(--status-archived);
color: var(--text);
}
7. theme.palette 配置
theme:
palette:
# 浅色模式(默认)
- media: "(prefers-color-scheme: light)"
scheme: default
primary: custom # 由 xiyin-brand.css --yin-color 接管
accent: custom # 由 xiyin-brand.css --xi-color 接管
toggle:
icon: material/weather-night
name: 切换到深色模式
# 深色模式
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: custom
accent: custom
toggle:
icon: material/weather-sunny
name: 切换到浅色模式
约定:
- ✅ primary / accent 都设为 custom,真实颜色由 xiyin-brand.css CSS 变量提供
- ✅ 浅/深色 toggle 必须保留(用户偏好)
- ❌ 不得改 primary 为 Material 预设色(如 indigo / blue)
8. plugins 配置
plugins:
- search:
separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;'
lang:
- en
- zh
- tags:
tags_file: 05-standards/tags.md # tags 索引页(P1 阶段创建)
# - macros 不启用(详见决策 2 = A,作者用 raw HTML + md_in_html 替代 macros)
9. 与下游规范的引用关系
flowchart TD
A["nav-display-spec.md<br>(本文档 · 站点级配置)"] -->|配置 mkdocs.yml| MK[mkdocs.yml]
A -->|定义模板规则| OV[overrides/main.html]
A -->|定义资源加载顺序| ASSETS[assets/javascripts/<br>assets/stylesheets/]
B["folder-structure-spec.md<br>(目录物理结构)"] --> A
C["md-writing-spec.md v2.0<br>(MD 写作契约)"] -->|frontmatter status / katex| A
D["format-spec-changelog.md<br>(10 条决议)"] -->|决议 4 / 7 / 8 / 10| A
E["brand-color-system.md v1.2<br>(色板)"] -->|status 徽章颜色| A
class A xyL3
class B,C xyL1
class D xyL2
class E xyL5
class MK,OV,ASSETS xyL010. 修订历史
| 版本 | 日期 | 修订人 | 关键变更 |
|---|---|---|---|
| v1.0.1 | 2026-05-11 | AlgoDepartment | 新增 §3「Stripe 三栏布局规范」专章 — 落地第一组导航方案决议(Demo 1 Stripe 风格);章节编号顺延(原 §3 加载顺序→§4 / 原 §4 nav indexes→§5 / 原 §5 status 徽章→§6 / 原 §6 palette→§7 / 原 §7 plugins→§8 / 原 §8 引用关系→§9) |
| v1.0 | 2026-05-11 | AlgoDepartment | 首版发布 · 涵盖 features / nav / 加载顺序 / status 徽章 / KaTeX 动态加载 7 大维度 |
下一步
本规范完成后,文档管理员智能体应:
1. 在 P0 阶段按 §1 配置 mkdocs.yml: theme.features
2. 按 §3 落地 Stripe 三栏布局 ⭐(11 个 CSS 变量 + Material 主题接管 + 9 项验收)
3. 按 §4 调整 extra_css / extra_javascript 加载顺序
4. 按 §4.2 在 overrides/main.html 添加 KaTeX 动态加载片段
5. 按 §5 创建 9 个一级目录的 index.md(用 §5.3 模板)
6. 按 §6 在 overrides/main.html 添加 status 徽章渲染逻辑 + 配套 CSS