05-内容与Markdown

1. 文章目录与文件约定

文件名不是 URL：

src/content/posts/我的第一篇文章.md 的 URL 由 frontmatter 里的 slug 决定。若 slug 是 my-first-post，URL 就是 /posts/my-first-post/。

但文件名影响两件事：

1. scripts/ensure-post-slugs.js 在 slug 缺失时，用 title（不是文件名）生成拼音 slug；
2. scripts/format-post-meta.js 与 update-post-updated.js 会用文件路径做状态键。

2. Frontmatter 字段完整参数表

---
title: "示例文章"
slug: shi-li-wen-zhang
index: 0
description: "一句话摘要，会用于 SEO 与列表摘要"
category: "示例"
tags: [Markdown, 教程]
# 连载（同一主题 3 篇以上、需按顺序阅读）才填写，零散文章留空：
# series: "系列名"
# series_order: 1
published: 2026-01-01 00:01:02
updated: 2026-01-01 00:01:03
draft: false
---

系列使用规则：系列是与分类/标签互不影响的可选属性。判定标准——同一主题已有 3 篇以上且需按顺序阅读（如连载教程）才建系列，零散文章不填。有 series 的文章会出现在 /series/ 系列页与独立的系列总览页；文章页会显示系列信息（头部一行 + 可折叠的系列目录），底部上一篇/下一篇在系列内按 series_order 相邻衔接。系列内排序规则：series_order 升序 → 发布时间升序兜底。

2.1 normalizeList() 的确切行为

// 输入字符串：按逗号拆分
"a, b, a"        → ['a', 'b']
// 输入数组
['Markdown', 'markdown', ' 教程 '] → ['Markdown', '教程']

处理步骤：split(',')（字符串时）→ trim() → 跳过空串 → 按 toLowerCase() 去重（保留首次出现的原始大小写）→ 输出。

2.2 category 传数组会怎样

category: [技术, 前端]

归一化得到 ['技术', '前端']，然后 transform(v => normalizeList(v)[0] ?? '未分类') → 最终 category = '技术'。第二项及之后会被静默丢弃，不要依赖多分类。

2.3 日期格式的坑

published / updated 在 content.config.ts 里经 parseDateAsUtc() 处理（无时区字符串补 Z 按 UTC 解析，YAML 裸日期已是 Date 对象则直通）。以下写法的解析结果：

建议统一用 YYYY-MM-DD HH:mm:ss（不加引号），与 scripts/new-post.js 生成的模板格式一致。脚本生成的 published 取的是当前 UTC 时间（如东八区本地 08:01:02 会写成 00:01:02）；站内显示统一按 UTC（formatDate / monthDay 用 dayjs.utc() 格式化），所有访问者看到一致的时间，不随时区变化。

2.4 slug 自动生成规则

scripts/ensure-post-slugs.js 的 titleToSlug(title)：

去重：若 slug 已被占用，依次尝试 {base}-1、{base}-2…；仍冲突则追加时间戳后缀（Date.now().toString(36).slice(-4)）。

「示例」→ slug 是什么？

title: "Markdown语法样例" → markdown-yu-fa-yang-li（见现有文章）。中文与英文混排时英文原样保留。

3. 新建文章的三种方式

方式一：脚本（推荐）

pnpm new-post my-first-post

生成 src/content/posts/my-first-post.md：

---
title: "my-first-post"
slug:
index: 0
description: "一句话摘要"
category: "未分类"
tags: []
published: 2026-01-01 12:00:00
---

从这里开始写作。

方式二：手动创建

在 src/content/posts/ 下新建 .md，粘贴上面的模板。slug 可以留空，pnpm dev / pnpm build 启动时会自动补全并写入文件。

方式三：子目录归类

src/content/posts/
├── 教程/
│   ├── 入门.md
│   └── 进阶.md
└── 随笔/
    └── 2026-01.md

loader 的 pattern: '**/*.md' 会递归扫描。相对链接的解析也支持跨目录（见#8）。

4. Markdown 语法支持矩阵

数学公式的 CSS 按需加载

katex/dist/katex.min.css 不再随文章页静态引入。PostPage.astro 在页面初始化时判断 document.querySelector('.katex')，只有正文真的渲染出公式才把 KaTeX 的 CSS 注入 <head>：

ts复制

12345

const { default: css } = await import('katex/dist/katex.min.css?inline')
const style = document.createElement('style')
style.dataset.katexCss = '1'   // 换页（Swup）后不重复注入
style.textContent = css
document.head.appendChild(style)

这里用 ?inline 取 CSS 文本而不是直接 import '…css'，是因为 astro.config.mjs 的 build.inlineStylesheets: 'always' 会把动态 import 出来的 CSS 资源一并内联进页面 HTML 并删掉资源文件——直接 import 会让公式页额外发出一个 404 的样式请求；取文本放进按需加载的 JS 分片里，才是真正的按需下载。

因此：无公式的文章页不会下载任何 KaTeX 资源；含公式的页面多下载一个 JS 分片 + woff2 字体（构建期由 postbuild.js 裁掉 ttf/woff，见 06-构建与脚本.md#5）。

自查方式：DevTools → Network 过滤 katex；或 performance.getEntriesByType('resource') 里搜索 katex。

内联 HTML 可用，但 RSS 里会被 XML 转义

页面渲染：✅ 正常。 已实测 dist/posts/markdown-yu-fa-yang-li/index.html 中 <kbd>Ctrl</kbd>、<span style="color:red;">红色文字</span> 都是以原生标签输出的（Astro 的 markdown 处理器内部开启了 allowDangerousHtml 并把 raw 节点保留到最终 HTML）。

RSS：⚠️ HTML 会被转义。 <content:encoded> 里输出的是 <p><kbd>Ctrl</kbd>…。这是 @astrojs/rss 对 content 字段做 XML 转义的既定行为（已用最小用例实测确认，与 renderMarkdownHtml 无关——后者本身输出的仍是原生 HTML）。

受影响的表现：部分阅读器会按字面显示 <p> 标签；也有阅读器会自动反转义后正常渲染。 若你重度依赖 RSS 的富文本展示，需要自行把 content:encoded 改成 CDATA 包裹，例如：

// src/pages/rss.xml.ts —— 自己拼 XML，而不是交给 @astrojs/rss
const escaped = html.replace(/]]>/g, ']]]]><![CDATA[>')
const customData = `<content:encoded><![CDATA[${escaped}]]></content:encoded>`

内联 HTML 的安全边界

Markdown 里写什么 HTML 就会输出什么（无净化）。不要在文章里粘贴来源不可信的内联 HTML/<script>——astro.config 的 rehypePlugins 里没有 rehype-sanitize。

不要用缩进创建代码块！

Markdown语法样例.md 明确提示：「请勿使用缩进 4 个空格或一个制表符来创建代码块，因为不会显示。」

原因是 remarkBreaks 把单换行转为 <br>，缩进块在解析阶段的边界行为与预期不符。请统一用围栏代码块 ```。

5. 提示容器（remarkContainers）

5.1 语法

:::info 标题可选
容器内容，支持 markdown 语法。
:::

:::tip
不写标题时，标题默认显示类型名（如 `tip`）。
:::

:::warning
警告内容
:::

:::danger
危险内容
:::

:::details 点击展开
details 是唯一可折叠的容器，标题变成 `<summary>`。
:::

5.2 五种类型对照表

5.3 解析规则（src/lib/md/remarkContainers.ts）

5.4 增加一个自定义容器类型（如 :::success）

需要改三个文件：

第 1 步：src/lib/md/remarkContainers.ts

const CONTAINER_TYPES = new Set(['info', 'tip', 'warning', 'danger', 'details', 'success'])

第 2 步：src/styles/markdown.css（加样式）

.post-content .md-container-success { border-left-color: #4a9d6a; }
.post-content .md-container-success .md-container-title { color: var(--wp-success-title); }

第 3 步：src/styles/main.css（加标题色的变量）

:root { --wp-success-title: #2f7048; }
.dark { --wp-success-title: #7bc39a; }

改 remarkContainers 后需要重启 dev

它在 astro.config.mjs 里被静态 import 进 markdown 处理器，改动后 Vite 不会热更新 markdown 配置，请重启 pnpm dev。

6. 代码块实现与可调参数

6.1 生成的 HTML 结构

<div class="code-block">
  <div class="code-header">
    <span class="code-lang"><svg …/>python</span>
    <button class="code-copy" type="button" onclick="window.__blogCopyCode(this)">
      <svg …/><span>复制</span>
    </button>
  </div>
  <div class="code-body">
    <div class="code-gutter"><span>1</span><span>2</span>…</div>
    <pre class="code-pre"><code class="language-python">…token 化的 HTML…</code></pre>
  </div>
</div>

6.2 支持的语言（Prism 语法）

src/lib/md/rehypeCodeBlock.ts 顶部 import 了这些 Prism 组件：

加一门语言：在 rehypeCodeBlock.ts 顶部追加 import 'prismjs/components/prism-xxx'（注意 Prism 组件有依赖顺序，例如 prism-jsx 需要在 prism-markup + prism-javascript 之后）。

6.3 语言图标映射

langIconMap（源码第 45–77 行）：

加语言图标：在 langIconMap 里加映射即可（图标常量需已存在于 src/lib/icons.ts，否则 IconName 类型会报错）。

6.4 未知语言的处理

function normalizeLanguage(raw) {
  const cleaned = raw.trim().toLowerCase().replace(/[^a-z0-9-]+/g, '')
  return Prism.languages[cleaned] ? cleaned : ''   // 不在 Prism 里则返回空串
}

6.5 服务端代码块的「硬编码中文复制按钮」

rehypeCodeBlock.ts 里写死了「复制」

源码第 110 行：

ts复制

1

`…<button class="code-copy" …>${iconSvg('mdi-content-copy')}<span>复制</span></button>…`

这个 复制 是构建期硬编码的中文。PostPage.astro 在客户端用 window.__blogCopyIdleHtml / __blogCopyDoneHtml（由 i18n 的 post.copy / post.copied 生成）覆盖它，所以最终显示是正确的。

但有一个副作用：代码块在 JS 加载前短暂显示「复制」。若你的站点非中文且在意这个 FOUC，请把 rehypeCodeBlock.ts 的复制按钮做成不含文本的空按钮（保留图标），完全交给客户端填充。

6.6 可调参数

7. 图片处理与 LQIP 占位

7.1 图片引用的三种写法

rehypeImages 会把每个 <img> 包成：

<span class="img-frame" style="--img-lqip:linear-gradient(135deg,#aabbcc 0%,#ddeeff 50%,#112233 100%)">
  <a class="img-lightbox" href="{src}" title="…">
    <img src="{src}" alt="…" loading="lazy" decoding="async" />
  </a>
</span>

7.2 LQIP（主色渐变占位）

7.3 图片路由 /content-images/[file]

src/pages/content-images/[file].ts 是一个 prerender = true 的静态路由：

支持的图片扩展名：.webp .png .jpg .jpeg .gif .svg .avif .ico .bmp

为什么用 hash 而不是原文件名？

好处是避免中文文件名 URL 编码问题、天然去重、可长缓存（文件内容变了路径不变，但通过重新构建会有新 hash… 注意：hash 只基于相对路径，不基于内容。改了图片内容但路径不变时 hash 不变，浏览器可能命中长缓存。此时需要清理缓存或改名）。

7.4 灯箱（PhotoSwipe）

由 PostPage.astro 的 initPhotoswipe() 初始化：

7.5 图片骨架状态机

8. 相对链接自动转换

8.1 支持的写法

8.2 解析流程（src/lib/md/rehypeRelativeLinks.ts）

1. 只处理 isRelativeSrc(href) 的链接（非 http(s)/非 //、非 /、非 #、非 data:）
2. 用 [?#] 拆分 pathPart 与 suffix（后缀会拼回结果）
3. resolveContentPath(pathPart, filePath)
   → 以 src/content/ 为根做安全拼接，遇到 .. 出界返回 null（并警告）
4. 查 .generated/post-index.json：
   - 命中 → 用 entry.slug
   - 未命中但扩展名是 .md/.markdown → 直接读文件 frontmatter 取 slug
   → 输出 /posts/{slug}/{suffix}
5. 若是图片扩展名 → resolveContentImage → /content-images/{hash}.ext
6. 其他 → 保持原样 + 警告

8.3 构建期警告一览

为什么链接失效只警告不报错？

因为预取（Swup preload）会请求该 URL 返回 404，但不影响页面正常显示。项目选择「构建期警告 + 保留原样」的宽松策略。请留意构建输出，及时修正。

9. 文章页面的 TOC（目录）

9.1 数据来源

render(post) 返回的 headings（Astro 内置，来自 rehypeSlug 生成的 id 与标题文本）。

9.2 两种呈现

9.3 可调参数（PostPage.astro 内常量）

改内容区宽度要同步 TOC

BaseLayout 的 <main class="max-w-[832px]"> 与 PostPage.css 的 left: calc(50% + 26rem) 是耦合的。832px 是玻璃卡片外框宽度（正文内容 800px + 左右 px-4 各 16px ），而 26rem = 416px = 832 / 2——侧栏是 fixed 定位，50% 从视口中线起算，偏移半个外框宽度即贴住卡片右缘。

换算公式：内容宽改为 W 时，外框 = W + 32，侧栏偏移 = calc(50% + (W + 32) / 2 px)。例如内容 900px → 外框 932px → 偏移 466px ≈ calc(50% + 29rem)。

参考 03-主题与样式定制.md#53-常用排版参数调整位置

9.4 高亮与滚动逻辑

上表「点击跳转」只针对同页目录链接。跨页面的锚点链接（如 markdown 相对链接带 #）由 BaseLayout 的点击委托接管：SPA 导航到页顶 → 加载后按同样的 80px 偏移平滑滚动（含直接打开 # 深链接场景），详见 07-页面与路由.md#84。

10. 内容创作完整流程示例

# 1. 新建文章
pnpm new-post my-post

# 2. 编辑 src/content/posts/my-post.md
#    填 title / description / category / tags / published
#    slug 留空，构建时自动生成

# 3. 元数据排序（可选，但推荐）
pnpm format-post-meta
#    → 输出：formatted N posts 或 all post meta already in canonical order

# 4. 本地预览
pnpm dev
#    → 访问 http://localhost:4321

# 5. 构建（会补 slug、生成 LQIP、生成搜索索引）
pnpm build

# 6. 检查构建警告（相对链接、LQIP 取色失败等）
#    7. 预览产物
pnpm preview

# 8. 提交（先 build 再 commit，让 slug/updated 改动一起进版本库）
git add -A && git commit -m "post: my-post"

pnpm format-post-meta 的字段顺序

scripts/format-post-meta.js 定义的规范顺序：

order = ['title', 'slug', 'index', 'description', 'category', 'tags', 'published']
last  = ['updated', 'draft']

最终顺序：order 中存在的字段（按序）→ 其他未列出的自定义字段（保持原相对顺序）→ last 中存在的字段（按序）。

加了自定义 frontmatter 字段（如 cover）后，它会落在「其他字段」区；想固定位置请把它加入 ORDER 或 LAST。