Docusaurus 博客文章的元数据配置详解

---
title: Docusaurus 博客文章的元数据配置详解
id: blog-front-matter-guide
description: 本文介绍如何在 Docusaurus 博客文章中配置 Front Matter，包括标题、链接、封面图、排序、摘要等，帮助你规范写作和管理内容。
slug: /blog-front-matter-guide
image: /img/ops/docusaurus/front-matter-cover.png
tags: [docusaurus, 博客搭建, markdown]
authors: [ghostwritten]
date: 2025-04-15
sidebar_position: 10
---

📘 什么是 Front Matter？

在使用 Docusaurus 写博客时，每篇 Markdown 文件的开头可以写一段以 — 包裹的配置块，这段 YAML 格式的内容就叫做 Front Matter，用于定义文章的元信息（metadata）。

这些配置可以控制文章的标题、路径、封面图、是否显示目录等内容。

✅ 常用配置项说明

下面是最常见的 Front Matter 配置项及其说明：

配置项	类型	说明
title	string	博客文章标题，显示在页面头部与浏览列表中。
id	string	文章的唯一 ID，通常等于 title 或英文名（可省略，默认为文件名）。
description	string	文章摘要，用于 SEO 和文章列表的简介显示。
slug	string	文章的访问路径，如 /kubernetes/intro，若为 / 则为首页。
date	string	文章发布日期，格式如 2025-04-15。
image	string	封面图 URL，推荐路径为 /img/xxx.png，注意不需要加 /static 前缀。
tags	array	用于分类文章或支持标签页。
authors	string/array	指定作者名，对应 authors.yml 中配置的 key（例如 ghostwritten）。
sidebar_position	number	控制文章在博客侧边栏中的排序位置（数字越小越靠前）。
hide_table_of_contents	boolean	设置为 true 可隐藏文章右侧目录。

✍️ 示例：完整 Front Matter 模板

---
title: Kubernetes 介绍
id: kubernetes-intro
description: 深入解析 Kubernetes 的起源、架构与未来趋势，揭示它如何重塑现代基础设施的控制逻辑。
slug: /kubernetes/intro
date: 2025-04-15
image: /img/ops/kubernetes/cover.png
tags: [kubernetes, 容器, 云原生]
authors: [ghostwritten]
sidebar_position: 1
hide_table_of_contents: false
---

🧠 补充说明

• slug 是最终生成的访问路径，不建议与文件夹结构重复配置。例如如果文章位于 blog/k8s/intro.md，而 slug 也设置为 /k8s/intro，访问路径就会是 /k8s/intro。
• image 路径推荐放置在 static/img 下，引用时使用 /img/… 的形式，不需要加 /static。
• tags 可用于生成标签云，或者按主题分类浏览。
• authors 建议统一维护在 authors.yml 中，可以定义作者头像、社交信息等。

🛠 提示：一些有用的技巧

• 博客封面图统一规范尺寸（例如 1200×630）可以优化在社交平台分享时的展示效果。
• 所有博客统一用 sidebar_position 排序，可以避免文章顺序混乱。
• 使用 date 可以让文章自动以时间顺序排序，即使文件名不是按照时间命名的。

🧩 博客 Markdown 模板

这是你未来撰写博客时可以复用的 Markdown 模板（Front Matter + 内容结构）：

---
title: 博客标题（推荐中文，便于阅读）
id: blog-唯一-id（推荐英文/拼音，便于区分）
description: 一句话摘要，用于 SEO 和首页卡片显示
slug: /blog/xxx（访问路径，比如 /blog/kubernetes-intro）
date: 2025-04-15
authors: [ghostwritten]
tags: [技术, kubernetes, 运维转前端]
image: /img/blog/kubernetes-intro/cover.png
sidebar_position: 1
hide_table_of_contents: false
---## 🧭 简介用 1～2 段介绍你写这篇文章的动机，场景或经历，让读者代入。---## 📚 正文结构建议### 一、背景阐述技术背景、遇到的问题或为什么要研究这个内容。### 二、分析 / 方案 / 原理具体内容深入展开，适配技术主题或经验总结。### 三、操作步骤 / 实践过程操作流程、代码示例、配置文件、截图等都放在这一节。### 四、总结 / 教训 / 反思总结你学到了什么，有什么经验教训、优化建议。---## ✍️ 附录（可选）- 🔗 参考链接
- 🛠️ 工具/插件列表
- 📁 示例文件链接

🧾 总结

通过合理使用 Front Matter，你可以：

• 提高博客的可读性与美观性
• 增强 SEO 效果
• 更容易维护作者、标签、路径等信息
• 为未来的内容结构调整做好准备

让每一篇文章，都成为有名字、有结构、有故事的存在。