Markdown 标签完全指南：行内标签与 Front Matter 标签

说到 Markdown 标签（tags），很多人第一反应是"这不是博客系统才有的功能吗"。确实，John Gruber 最初设计 Markdown 的时候根本没有标签这个概念 [^1]。但随着 Markdown 被越来越多人用来管理笔记、写博客、维护文档，标签就成了刚需——你总得有个办法把几百篇文章按主题归类吧。

这篇文章把 Markdown 生态里的标签彻底讲清楚：行内标签（#tag）怎么写，Front Matter 里的 tags 字段怎么用，不同平台之间有什么差异，以及怎么取一个好听又好用的标签名。

Markdown 标签速查表

先上一张总览表，方便快速查阅。每种标签后面都会展开说明。

标签类型	写法	适用场景	典型平台
行内标签	#标签名	在正文中随时打标签	Obsidian、Logseq
嵌套标签	#父级/子级	按层级组织标签	Obsidian
Front Matter 列表	tags: [a, b]	文章级元数据分类	Jekyll、Hugo、VitePress
Front Matter 多行	tags: + - a	同上，适合标签多的情况	同上
Front Matter 字符串	tags: a b c	空格分隔的标签（Jekyll 专用）	Jekyll

关键认知：Markdown 标签不是原始规范的一部分。它是由具体工具（静态站点生成器、笔记软件）各自实现的，所以不同平台的语法和行为都有差异。下面分两类来讲。

行内标签：在正文里随手标记

行内标签就是直接在 Markdown 正文里写 #标签名。它看起来像社交媒体的话题标签（hashtag），但功能上用来给笔记分类。

Obsidian 行内标签

Obsidian 是目前对行内标签支持最完善的工具。在正文任意位置写 #标签名，Obsidian 就会自动识别并在左侧标签面板里汇总 [^2]。

今天学习了 Markdown 的基本语法 #markdown
这个笔记和 JavaScript 有关 #javascript

几个细节规则：

1. 标签前面必须有空格或位于行首——这是#标签 不会被识别，这是 #标签 才会
2. 标签后面不能紧跟普通文字——#标签后面 只会识别 #标签（空格后面是结束）
3. 不允许有空格——#我的 标签 只会识别 #我的，要写 #我的标签 或用下划线 #我的_标签
4. 大小写不敏感——#Markdown 和 #markdown 是同一个标签
5. 数字可以出现——#2026计划 是合法标签，但纯数字 #123 在某些版本中可能不生效

嵌套标签：用斜杠组织层级

Obsidian 支持用 / 创建嵌套标签，相当于给标签建了一个文件夹结构 [^2]：

#inbox/待读
#inbox/待处理
#项目/前端
#项目/后端

在标签面板里，#inbox 下面会折叠显示 待读 和 待处理 两个子标签。搜索 #inbox 也会匹配所有子标签。这个功能在标签多了以后特别有用——不然一长串扁平标签根本没法看。

嵌套层数没有硬性限制，但实际使用中两层到三层就够了，太深反而增加管理成本。

行内标签的局限

行内标签最大的问题是依赖特定工具。#标签 这个写法在 Jekyll、Hugo 这些静态站点生成器里完全没有意义——它们只认 Front Matter 里的元数据。GitHub 上渲染 Markdown 时，#标签 会被当作一级标题。

所以如果你用 Obsidian 写笔记，行内标签很方便。但如果你的文件最终要发布到博客或者 GitHub，还是得靠 Front Matter 标签。

Front Matter 标签：在元数据里分类

Front Matter 标签是写在 YAML 头信息 里的 tags 字段，用来给整篇文章打标签。这是静态站点生成器和大部分工具都支持的方式。

YAML 列表语法

两种写法等效，选你喜欢的就行：

行内写法（适合标签少的情况）：

---
title: Markdown 标签指南
tags: [markdown, tags, 教程]
---

多行写法（适合标签多的情况）：

---
title: Markdown 标签指南
tags:
  - markdown
  - tags
  - 教程
---

我个人倾向多行写法，因为增删标签时 Git diff 更清晰，不会因为一行改动了整个数组而产生歧义。

Jekyll 的空格分隔语法

Jekyll 有个独特的写法——用空格分隔标签，直接写成字符串 [^3]：

---
title: 我的文章
tags: markdown tags 教程
---

这个写法只有 Jekyll 认。Hugo、Hexo、VitePress 都只接受数组格式。实测发现，如果你在 Jekyll 里同时写了 tags: [a, b] 这种数组格式，Jekyll 也能正确解析，所以在 Jekyll 项目里用数组写法也没问题，而且跨平台兼容性更好。

Hugo 的多格式支持

Hugo 是少数支持三种 front matter 格式的静态站点生成器 [^4]：

---
title: 我的文章
tags: [markdown, tags]
---

# TOML
+++
title = "我的文章"
tags = ["markdown", "tags"]
+++

# JSON（极少用）
{
  "title": "我的文章",
  "tags": ["markdown", "tags"]
}

三种格式里，Hugo 都把 tags 当作 taxonomies（分类法）来处理，会自动生成 /tags/markdown/ 这样的标签页面。

Obsidian 里两种标签怎么配合

Obsidian 比较特殊——它同时支持行内标签和 Front Matter 标签，而且两种标签会被合并到同一个系统里 [^2]。也就是说，不管你在正文里写 #javascript 还是在 front matter 里写 tags: [javascript]，Obsidian 都会在标签面板的同一个 javascript 条目下汇总。

那两种方式该怎么选？我的习惯是：

• Front Matter 标签用于文章级分类——这篇文章"是什么"，比如 tags: [教程, markdown, 前端]
• 行内标签用于段落级标记——这段内容"涉及什么"，比如 #待复习 #重要 #bug

这样分工的好处是：Front Matter 标签适合批量检索"所有教程类文章"，行内标签适合在阅读时快速定位"哪些段落标记了重点"。

Markdown 标签命名规则

不管用哪种标签形式，取名字都有一些通用规则。这部分是我踩了不少坑之后总结的。

允许的字符

字符	行内标签	Front Matter 标签	说明
中文	✅	✅	Obsidian 完美支持中文标签
英文字母	✅	✅
数字	✅	✅
下划线 _	✅	✅	用于替代空格
短横线 -	✅	✅
斜杠 /	✅（Obsidian）	❌	行内标签用于嵌套层级
空格	❌	✅（用引号包裹）	行内标签遇到空格就截断
#	❌	✅（用引号包裹）	和行内标签前缀冲突

命名建议

保持简短——标签不是描述，2-4 个词足够了。#前端 比 #前端开发技术栈 好用得多。

统一风格——要么全用中文（#前端），要么全用英文（#frontend），混用会让标签面板很乱。我之前就有个坏习惯，#javascript 和 #前端 混着打，后来想找所有前端相关的笔记，发现分散在两个标签下面。

避免同义词——#js 和 #javascript 是两个不同的标签，选一个坚持用。可以在标签面板里把不常用的那个删掉，Obsidian 会提醒你哪些笔记用过它。

不同平台的标签差异对比

一张表看完各平台对 Markdown tags 的支持情况：

特性	Obsidian	Jekyll	Hugo	Hexo	MkDocs Material
行内标签	✅	❌	❌	❌	❌
嵌套标签	✅	❌	✅	❌	✅（付费）
Front Matter tags	✅	✅	✅	✅	✅
自动标签页	❌	✅	✅	✅	✅
YAML 数组格式	✅	✅	✅	✅	✅
TOML 格式	❌	❌	✅	❌	❌
标签面板/索引	✅	需插件	✅	需插件	✅

有一个容易混淆的点：tags 和 categories 的区别。在 Hexo 和 Jekyll 里，categories 是有层级的（一个文章只能属于一个分类链），tags 是扁平的（一个文章可以有多个标签）[^3]。但 Obsidian 不区分这两个概念——它只有标签。

常见问题

Front Matter 里的 tags 和 keywords 有什么区别？

tags 是分类标签，用来组织内容，通常会在网站上展示为可点击的标签链接。keywords 是 SEO 关键词，写在 HTML meta 标签里，不会在页面上显示。有些主题会把 tags 同时用作 SEO 关键词，但语义上它们是不同的东西。

标签太多了怎么办？

标签膨胀是真实存在的问题。我有一次整理笔记，发现标签面板里有 200 多个标签，其中一半是只出现过一次的。后来我做了个清理：

1. 合并同义词——把 #js、#JS、#javascript 合并为 #javascript
2. 删除低频标签——只出现过 1-2 次的标签，要么合并到更宽泛的标签，要么直接删除
3. 用嵌套标签替代扁平标签——#css #css-动画 #css-布局 改为 #css/动画 #css/布局

目标是把标签控制在 50 个以内，每个标签至少关联 3 篇文章。

行内标签和 Markdown 标题冲突怎么办？

在标准 Markdown 里，# 开头是一级标题。所以 #标签 在 GitHub、GitLab 上渲染时会被当成标题，而不是标签。只有 Obsidian、Logseq 这类笔记工具才会把正文中的 #单词 识别为标签。

如果你的 Markdown 文件要在多个平台使用，行内标签只放在 Obsidian 里用，正式发布的内容用 Front Matter 标签。

说实话语法本身没几行，但坑都在细节里。搞清楚你的文件最终要在哪个平台上使用，选对标签形式，然后坚持统一的命名习惯，标签系统就能真正帮到你而不是添乱。

参考来源

[^1]: John Gruber, Markdown: Syntax, Daring Fireball — 原始 Markdown 规范中未定义标签概念 [^2]: Obsidian Help, Tags, help.obsidian.md — Obsidian 标签功能官方文档 [^3]: Jekyll Documentation, Front Matter Defaults, jekyllrb.com — Jekyll 对 tags 和 categories 的处理方式 [^4]: Hugo Documentation, Front Matter, gohugo.io — Hugo front matter 三种格式及 taxonomies 支持