|
示例文章标题
副标题或装饰文字
写在前面
这篇文章演示了构建脚本支持的全部功能。包括自定义 TOC 目录、 自动提取目录、脚注系统、 标签分类、代码块、表格等等。
关于构建脚本本身的详细介绍，可以看这篇构建脚本全解析。
正文第一节：自动目录与自定义目录
如果文章里使用了
<font size="5" color="#ff66cc">
作为章节标题， 构建脚本会自动提取这些标题生成 TOC 目录[1]。 每个标题前会自动插入
<a name="toc-N">
锚点，侧边栏的目录链接可以直接跳转。
如果在文章顶部写了
<!-- toc: 条目1, 条目2 | custom-anchor -->， 构建脚本会优先使用自定义目录[2]。 自定义目录的每个条目可以只写标题（自动分配
toc-N 锚点）， 也可以用
标题 | 锚点名 的格式指定锚点。
如果自定义目录存在，文章里需要放置
<!-- toc-anchor -->
标记来告诉构建脚本在哪里插入锚点。标记会按顺序依次替换：第一个标记对应第一个目录条目，以此类推。
本篇文章同时演示了两种方式：前两个目录项用了自定义目录 +
<!-- toc-anchor --> 标记，
后面这个自动目录章节则是靠标题自动提取的[3]。
第二个章节：脚注系统详解
脚注是学术写作和长文章的重要工具。本项目的脚注系统完全在构建时处理， 不依赖
JavaScript[4]。
正文中使用 [^数字] 引用脚注，文末用
[^数字]: 内容 定义脚注。
构建脚本会做三件事[5]：
1. 将正文中的
[^N] 替换为带锚点链接的上标数字
2. 将文末的
[^N]: 定义 收集成脚注区域
3. 在文章底部渲染脚注列表，每一条都可以点击跳回正文引用处
脚注定义支持两种格式：
格式一：带段落标签（推荐，支持跨行）
<p> 标签包裹的脚注定义。
这种方式支持跨行，脚注内容可以很长， 可以包含
<code> 标签、链接等各种 HTML 元素。
构建脚本会正确提取完整的跨行内容。
格式二：裸定义（单行）
点击正文中的脚注编号
[8] 可以跳到底部注释，
再点击注释左侧的编号可以跳回正文[8]。 这是 HTML 3.2 时代就支持的标准锚点跳转机制。
脚注演示
下面演示脚注在代码和技术文章中的典型用法。构建脚本的版本管理遵循了几个原则
[9]： 每次修改后手动运行构建、用 Git 追踪源码而非输出文件、 通过
build.cmd 统一构建入口。
构建流程的设计也考虑了实用性[10]。 如果想深入了解构建系统的技术细节，可以阅读
构建脚本全解析
这篇文章。
代码与表格
PowerShell 构建脚本的核心调用方式：
powershell -ExecutionPolicy Bypass -File scripts/build.ps1 `
-PageName "blog-SLUG" `
-Title "页面标题" `
-ContentFile "src/content/pages/blog/content-SLUG.html"
下面是一个表格示例：
|
功能
|
用法
|
说明
|
| 自定义 TOC |
<!-- toc: 标题 | 锚点 -->
|
逗号分隔，锚点可选 |
| 自动 TOC |
<font size="5" color="#ff66cc">
|
从标题自动提取 |
| TOC 锚点标记 |
<!-- toc-anchor -->
|
自定义目录的跳转目标 |
| 脚注引用 |
[^N]
|
正文中的上标链接 |
| 脚注定义 |
<p>[^N]: 内容</p>
|
带标签可跨行 |
| 标签分类 |
<!-- tags: A, B -->
|
逗号分隔，显示在侧边栏 |
| 草稿标记 |
<!-- draft: true -->
|
默认构建跳过 |
更多细节请参考项目根目录下的scripts/build.ps1
源码。
| [1] | 自动提取的标题正则：<font[^>]*size="5"[^>]*color="#ff66cc"[^>]*>。 构建脚本按匹配顺序从后往前插入锚点并生成目录列表，确保锚点位置正确。 |
| [2] | 自定义目录使用逗号分隔多个条目，每个条目可选
标题 | 锚点名 格式。
如果省略锚点名，自动分配 toc-1、toc-2
等。 |
| [3] | 如果自定义目录存在且非空，就使用自定义目录；如果不存在或为空，
则自动从标题提取。两种方式互斥，不会同时生效。 |
| [4] | JavaScript 在复古浏览器（IE5.5 等）中可能不可用或被禁用。 纯 HTML
锚点跳转是 HTML 3.2 标准特性，兼容性最好。 |
| [5] | 脚注处理在构建脚本中分两步完成：第一步匹配带
<p>
等标签包裹的定义（支持跨行），第二步匹配裸定义（单行）。
两步都完成后统一替换引用并渲染脚注区域。 |
| [6] | 这是一个跨行的脚注示例。
这段脚注内容横跨多行，包含了中文、英文 Mixed Content、 以及
inline code 和内联样式。
这在写长注释时非常实用，不用把所有内容挤在一行里。 |
| [7] | 裸定义不用标签包裹，内容只能写一行。适合简短说明。 |
| [8] | 正文中提到的
[^8] 本身就是一个脚注引用。
这句话出现在正文里，点击它可以跳到文末这条注释，再点击编号跳回去。
这就是脚注系统的"自指演示"。 |
| [9] | 构建脚本每次修改后手动运行，Git 追踪源码文件而非
dist/
输出目录。这样可以保持输出目录干净，且每次构建都是确定性的。 |
| [10] | 单页面构建只替换占位符不扫描博客目录，速度很快。
如果新增了文章，需要先运行
generate-archive.ps1 更新 latest-posts
组件，再运行 build.ps1。 |
|
