Markdown 博客 frontmatter 写法规范与常见坑
用 Markdown 存文章是静态博客最常见的方式，文章顶部的 YAML 块叫 frontmatter。写法看着简单，但几个细节会直接影响构建、URL 和 SEO。
最小可用示例
---
title: "用 Cloudflare 反代 Supabase"
slug: cloudflare-supabase-proxy
date: "2026-11-14"
tags: ["建站", "Cloudflare", "Supabase"]
description: "Supabase 国内访问慢，用 Cloudflare Worker 做一层反代即可显著改善，本文给出完整配置。"
---
正文从这里开始。
字段约定
| 字段 | 必填 | 说明 |
|---|---|---|
| title | 是 | 页面标题，尽量含关键词，不要堆砌 |
| slug | 建议 | URL 路径，英文短横线，不填则用文件名 |
| date | 是 | 发布日期，用于排序和 sitemap 的 lastmod |
| tags | 建议 | 数组，影响「相关文章」推荐 |
| description | 是 | meta description，60–120 字 |
坑一：日期不加引号会变成对象
date: 2026-11-14
YAML 会把这种写法解析成 Date 对象，而不是字符串。如果代码里直接用 post.date 渲染，可能得到一长串带时区的字符串，甚至构建报错。
两种处理方式，任选其一：
date: "2026-11-14"
或者代码里统一归一化：
const date = data.date instanceof Date
? data.date.toISOString().split("T")[0]
: String(data.date);
本站用的是后者，同时在 frontmatter 里也加引号，双保险。
坑二：中文 slug 会让 URL 变成乱码
slug: 什么是Root
生成的是 /blog/什么是Root/，浏览器地址栏里复制出来会变成一长串 %E4%BB%80%E4%B9%88...，分享、统计、日志里都不好看。
新文章建议用英文短横线：
slug: what-is-android-root
已经发布的中文 slug 不建议随便改——改了旧链接就 404，需要配 301，得不偿失。
坑三：description 超长被截断
搜索结果里 description 只显示约 80 个汉字。写太长会被截断，写太短（少于 25 字）又容易被判为无效描述。
建议 60–120 字，包含核心关键词，用一句话说清「这篇解决什么问题」。不要复制正文第一段，那是模板化做法。
坑四：tags 写成字符串
tags: 建站, Next.js
解析出来是一个字符串 "建站, Next.js"，按标签匹配时永远匹配不到。正确写法是数组：
tags: ["建站", "Next.js"]
代码侧最好做兼容：
const tags = Array.isArray(data.tags)
? data.tags.map(String)
: typeof data.tags === "string"
? [data.tags]
: [];
坑五：正文第一行就写 H1
---
title: "标题"
---
# 标题
页面模板通常已经渲染了 <h1>{title}</h1>，正文再写一次 H1 就会出现两个一级标题，不利于 SEO 结构。
正文从 ## 开始，把 H1 交给模板。
坑六：空文件或只有 frontmatter
只有 frontmatter、没有正文的文章会被判为「薄内容」，不但没有流量，还会拉低整站质量评分。写之前先想清楚这篇文章解决什么问题，写不出 800 字就先别发。
推荐的写作结构
---
title: "..."
slug: "..."
date: "..."
tags: [...]
description: "..."
---
一句话说明解决什么问题。
## 问题现象
## 原因
## 解决步骤
### 步骤 1
### 步骤 2
## 常见问题
### 问句 1？
### 问句 2？
## 相关阅读
- [站内另一篇](/blog/xxx/)
这种结构对用户友好，对搜索引擎也友好：有明确的问题描述、分步解答和 FAQ，容易被识别为教程类内容。
常见问题
frontmatter 用 TOML 还是 YAML？
绝大多数静态站点生成器默认 YAML（--- 包裹），这是通用性最好的选择。
能不能在 frontmatter 里写自定义字段？
可以。gray-matter 会把所有字段放进 data，自定义字段如 author、cover、draft 都能读出来，用于控制是否发布或渲染封面。
草稿怎么隐藏？
加 draft: true，然后在读取文章时过滤掉。静态站点最好把草稿放在单独分支，避免误发布。
修改文章日期会影响排序吗？
会。日期既用于列表排序，也用于 sitemap 的 lastmod。小幅修改不建议改日期，大改可以更新。