基础篇：Markdown 内容规范：文章、标签、系列如何被网站识别

Markdown 本身只是文本。

如果想让一篇 Obsidian 笔记被网站稳定识别，还需要给它补充一些结构信息：标题是什么、记录什么时候发布、有哪些标签、是否属于某个系列、是不是草稿。

这些信息通常写在文章开头的 Frontmatter 里。

1. 为什么需要内容规范

内容规范不是为了增加写作负担。

它解决的是几个很实际的问题：

网站如何生成文章标题和摘要
搜索索引如何识别正文、标签和系列
系列页如何知道文章顺序
草稿如何避免误公开
插件如何在发布前做校验
未来迁移到其它工具时，内容结构是否还能被读懂

如果没有这些字段，文章当然也能写，但网站只能把它当成一篇普通 Markdown。内容越来越多以后，标签、系列、搜索和发布状态都会变得难以维护。

2. 最小文章字段

一篇可以公开发布的文章，建议至少包含这些字段：

---
title: "PVE 网络规划"
slug: pve-network-planning
description: "记录一次 Homelab 网络规划实践。"
publishedAt: 2026-07-27
tags:
  - Homelab
  - PVE
  - Network
draft: false
explorations:
  - id: personal-knowledge-asset-system
    title: 个人知识资产发布系统
    stage: Obsidian 个人网站搭建
---

这些字段分别承担不同作用：

字段	用途
`title`	文章标题，用于文章页、列表页和 SEO 标题
`slug`	文章 URL，建议稳定，不要频繁修改
`description`	摘要，用于列表、搜索和页面描述
`publishedAt`	发布时间，用于排序和归档
`tags`	横向主题入口，用于标签页和相关文章
`draft`	是否草稿，避免未完成内容误公开
`explorations`	长期探索方向，用于把文章和系列沉淀到更大的问题脉络里

写作时不需要反复记这些字段。后续插件可以通过模板创建文章，并在发布前检查是否缺字段。

3. 文件名和公网链接分开

在 Obsidian 里，文件名可以直接使用中文标题。

例如：

Obsidian个人知识网站搭建指南/
  入门篇：为什么要用 Obsidian 搭建个人知识网站.md
  基础篇：Markdown 内容规范：文章、标签、系列如何被网站识别.md
  进阶篇：Obsidian 个人网站搭建方式怎么选.md

这样在本地 Vault 里阅读、搜索和整理都更直观，也更符合日常写作习惯。

公网 URL 则交给 Frontmatter 里的 slug：

title: "基础篇：Markdown 内容规范：文章、标签、系列如何被网站识别"
slug: markdown-content-schema-guide

发布后访问地址仍然保持简洁稳定：

/blog/markdown-content-schema-guide/

这样本地和公网各自负责不同事情：

位置	建议写法	主要作用
Obsidian 文件名	中文标题	方便本地阅读、搜索和管理
Frontmatter `title`	正式文章标题	用于页面展示、文章列表和 SEO 标题
Frontmatter `slug`	英文短链接	用于稳定 URL、分享链接和搜索收录

文件名可以随着写作习惯保持自然，公网链接则尽量稳定。即使以后调整 Obsidian 里的文件夹和文件名，只要 slug 不变，已经发布出去的文章地址就不会变。

4. 标签怎么写

标签适合表达横向主题。

比如一篇文章可以同时属于：

tags:
  - Homelab
  - PVE
  - DNS
  - Tailscale

这样它既可以出现在 Homelab 相关内容里，也可以被 DNS、Tailscale 等主题检索到。

标签的价值在于不用强行选择唯一目录。很多技术文章天然跨主题，用标签表达会更自然。

5. 系列怎么写

当一个方向的文章越来越多，就可以把它们组织成系列。

series:
  id: homelab-build
  title: "Homelab 建设手记"
  description: "从硬件、虚拟化、网络到服务部署的长期建设记录。"
  order: 3

系列适合表达纵向路线。

比如 Homelab 可能会逐渐形成：

服务器选型
PVE 安装
网络规划
DNS 和远程访问
容器服务
备份和自动化

一开始没有系列也没关系。先写文章，等内容积累到一定程度，再整理成系列，反而更贴近真实探索过程。

一篇文章建议只属于一个系列。因为系列负责组织连续阅读路线，order 也只对应这一条路线里的位置。跨主题关联可以交给标签和探索方向，不必把同一篇文章塞进多个系列。

6. 探索方向怎么写

探索方向用来表达：这篇文章属于哪段长期问题意识。

它和 series 一样是可选字段。文章不填写探索方向也可以正常发布；只有当这篇内容确实属于某个长期探索主题时，再补充 explorations 即可。

它不是目录，也不是标签，更不是目标进度。它回答的是：

这篇文章正在靠近哪个长期问题？
它沉淀到了哪个阶段？
后面还会继续关注什么？

可以这样写：

explorations:
  - id: personal-knowledge-asset-system
    title: 个人知识资产发布系统
    stage: Obsidian 个人网站搭建
    description: 围绕 Markdown、Obsidian、公开站和个人服务器，探索如何把本地笔记沉淀成可发布、可迁移的长期知识资产。
    next:
      - Obsidian 插件发布
      - 服务器一键安装
      - 私有 Hub 安全边界

explorations 是一个列表，一篇文章可以关联多个探索方向：

explorations:
  - id: personal-knowledge-asset-system
    title: 个人知识资产发布系统
    stage: Obsidian 插件发布
  - id: tooling-productivity
    title: 工具效率优化
    stage: 发布流程自动化

这种写法适合一篇文章同时服务多个长期问题的情况。比如一篇发布插件实践，既和个人知识网站有关，也和日常工具效率有关。

它和文章、标签、系列的关系可以这样理解：

组织方式	解决的问题
文章	这一次具体沉淀了什么
标签	这篇内容横向关联哪些主题
系列	这组文章怎么连续阅读
探索方向	这些产出长期在靠近什么问题

探索方向可以直接关联文章，也可以通过系列间接关联文章。

早期探索时，可能只是几篇零散文章；内容越来越多以后，再整理成系列。只要这些文章的 explorations.id 一致，网站就能自动把它们聚合到同一个探索方向下。没有填写 explorations 的文章，则只作为普通文章展示，不会被强行归入某个长期方向。

7. 草稿和公开状态

draft 用来控制内容是否公开。

draft: true

适合这些状态：

文章还没写完
图片和附件还没整理
里面有不适合公开的信息
需要先在 Hub 里预览

公开前再改成：

draft: false

这个字段很小，但很重要。它让写作过程和公开发布之间有一个缓冲区。

8. 附件和图片

图片、Excalidraw、图表导出文件和其它附件，最好跟文章形成稳定关系。

文章里引用图片和附件时，尽量使用相对路径。这样 Markdown 和附件之间的关系由文件本身维护，而不是依赖某个固定域名、绝对路径或平台地址。后续整理文件夹、迁移 Vault、同步到服务器时，只要文章和附件一起移动，引用关系就更不容易断。

一种比较清晰的方式是：

posts/
  PVE 网络规划.md
  PVE 网络规划/
    topology.png
    network.excalidraw
    checklist.pdf
    meeting-note.mp3

这样迁移时不会只带走 Markdown，却丢掉图片和图表源文件。

网页展示时，附件按用途分开处理：

类型	写法	网页效果
图片	`![网络拓扑](./PVE 网络规划/topology.png)`	直接展示在正文中
Excalidraw	保留 `.excalidraw`，正文引用导出的 SVG/PNG/WebP	网页展示导出图，源文件方便后续编辑
PDF、Office、ZIP、CSV	`[检查清单](./PVE 网络规划/checklist.pdf)`	单独成段时展示为下载卡片
MP3、M4A、OGG、WAV	`[会议录音](./PVE 网络规划/meeting-note.mp3)`	单独成段时展示为音频播放器
外部视频	`[演示视频](https://www.bilibili.com/video/...)`	单独成段时展示为外部视频卡片

不建议把本地视频直接放进博客目录。视频文件通常很大，容易拖慢构建、备份和迁移。更稳妥的方式是把视频放在 B 站、YouTube、Vimeo 或自己的视频服务里，文章中保留外部视频链接。

后续插件也可以根据这个约定自动检查附件是否存在，并在发布时一起同步到服务器。

9. 为什么这样方便迁移

这套规范没有把内容绑定到某个数据库里。

它仍然是：

Markdown
Frontmatter
附件

如果以后换成 Hugo、Astro、Jekyll、MkDocs 或其它 Markdown 工具，大部分内容仍然可以继续使用。真正有价值的不是某个页面模板，而是这些可读、可迁移、可整理的原始文件。

10. 一句话总结

Markdown 负责写作内容，Frontmatter 负责让网站理解内容。

标题、标签、系列、探索方向、草稿状态和附件约定组合起来，才能让一批本地 Obsidian 笔记变成可检索、可发布、可迁移，也能持续沉淀长期问题意识的个人知识网站。