frontmatter-guide

Front Matter 配置指南（Obsidian 创作参考）

本指南说明如何通过 Markdown 文件头部的 --- Front Matter 控制页面行为。创作时使用 Obsidian 编辑这些字段即可，无需改动代码。

一、普通笔记

普通笔记放在 content/ 下的任意位置，默认使用 note.njk 布局，无需写 layout。

最简示例

YAML
---
title: 我的笔记
description: 一句话描述，用于 SEO 和搜索摘要
tags: [技术, 笔记]
category: 学习
created: 2026-09-03
updated: 2026-09-03
---

字段速查表

字段类型必填默认说明
title字符串否文件名页面标题（h1、浏览器标签、文章列表显示）
description字符串否-SEO 描述 + 搜索摘要
tags数组/字符串否-标签，自动链接到 /tags/<标签>/
tag字符串否-单个标签，与 tags 等价
categories数组/字符串否-分类，自动链接到 /categories/<分类>/
category字符串否-单个分类，与 categories 等价
created日期否文件创建时间创建日期（YYYY-MM-DD），用于排序和展示
updated日期否跟随 date/created/文件修改时间更新日期
date日期否-同时作为 created/updated 的备选
permalink字符串否自动生成自定义 URL
layout字符串否note.njk使用的布局模板（见下）
hideSidebar布尔否false隐藏右侧边栏（目录 + 反向链接）
hideTitle布尔否false隐藏页面顶部大标题
cssclasses字符串/数组否-添加到文章容器的自定义 CSS 类
eleventyExcludeFromCollections布尔否false从文章集合/搜索/反向链接中排除
excerpt字符串否description搜索摘要（低优先级，一般用 description 即可）

日期字段优先级

  • 创建日期：created → date → 文件创建时间
  • 更新日期：updated → date → created → 文件修改时间

二、URL 规则（重要）

URL 由文件名决定，而不是 title：

文件位置生成 URL
根目录 content/_index.md/
根目录 content/foo.md/foo/
子目录 content/dir/_index.md/dir/
子目录 content/dir/foo.md/dir/foo/
content/_404.md/404.html

自定义 URL 用 permalink，例如 permalink: /about/。目录类 URL 建议保留结尾 /。

⚠️ 重命名文件会改变 URL，导致外部链接失效；Obsidian 双链 [[文件名]] 和反向链接依赖文件名，发布后尽量不要重命名。

三、布局模板（layout）

layout 值用途示例页面
note.njk普通笔记（默认，可不写）所有普通笔记
home.njk首页content/_index.md
article-list.njk文章列表页（文件夹/标签/分类）各文件夹 _index.md
taxonomy-index.njk标签/分类索引页_tags.md、_categories.md
404.njk404 页面_404.md

四、特殊页面模板

首页 content/_index.md

YAML
---
layout: home.njk
hideSidebar: true
hideTitle: true
eleventyExcludeFromCollections: true
---

正文即首页欢迎内容；garden.config.js 的 homepage.customArticlePath 也可指定其他笔记作为首页文章。

404 页面 content/_404.md

YAML
---
title: "页面走丢了"
layout: 404.njk
permalink: /404.html
eleventyExcludeFromCollections: true
hideSidebar: true
---

标签索引 content/_tags.md

YAML
---
title: 标签
layout: taxonomy-index.njk
eleventyExcludeFromCollections: true
taxonomyType: tags
hideSidebar: true
permalink: /tags/
---

分类索引 content/_categories.md

YAML
---
title: 分类
layout: taxonomy-index.njk
eleventyExcludeFromCollections: true
taxonomyType: categories
hideSidebar: true
permalink: /categories/
---

文件夹列表页 content/<文件夹>/_index.md

每个内容文件夹放一个 _index.md，即可生成该文件夹的文章列表页：

YAML
---
title: 运维学习
description: Linux 运维与服务器管理笔记
layout: article-list.njk
hideSidebar: true
listType: "folder"
permalink: /运维学习/
---

标签页 /tags/<标签>/、分类页 /categories/<分类>/ 由系统根据 front matter 自动生成，无需手动创建。

五、标签与分类使用要点

  • 单复数写法都支持：tags: [A, B] 或 tag: A；categories: [A] 或 category: A。
  • 一篇笔记可设置多个标签/分类。
  • 标签/分类名称会作为 slug 拼进 URL，如 tags: [深度学习] → /tags/深度学习/。
  • 无标签文章自动归入 /tags/untagged/，无分类文章归入 /categories/uncategorized/。

六、Obsidian 创作提示

  • 在 Obsidian 的 Properties（属性）面板编辑上述字段即可；title、description、tags、created、updated、date、cssclasses 都是 Obsidian 原生识别的属性。
  • .obsidian/ 目录不要提交到 git（已在 .gitignore 中忽略）。
  • 图片放在笔记同目录，用 ![[图片.png]] 引用，构建时自动复制；用 ![[图片.png|500]] 可控制显示宽度。
  • 双链 [[其他笔记]] 自动解析为站内链接，反向链接会在侧边栏展示。
  • 支持 Obsidian Callout 语法：> [!note]、> [!warning]、> [!tip] 等。
  • 新建文件夹 + _index.md 会自动出现新的列表页；记得在 _index.md 中写好 permalink 和 title。

七、常见场景速查

我想...怎么做
发布一篇新笔记在 content/ 任意子目录新建 .md，写好 title/tags/category/created
新建一个栏目新建文件夹并添加 _index.md（layout: article-list.njk + listType: "folder"）
某页不想要侧边栏加 hideSidebar: true
某页不要出现在列表/搜索里加 eleventyExcludeFromCollections: true
给某页自定义 URL加 permalink: /xxx/
修改文章排序修改 created/updated 字段即可