××××

📄 文档表头配置说明

📂纸鸢博客配置/文档类说明
💬

纸鸢博客文档 frontmatter 完整配置指南

📅发布于2026-04-01
⏱️阅读时间11 分钟
📝3068 字
📁分类教程
🏷️标签
文档配置教程

📋 文档表头配置说明

本文档详细介绍纸鸢博客中 Markdown 文档的 frontmatter 表头配置，所有配置项均为可选，按需添加即可。

💡 提示：所有字段值都可以不使用引号包裹，除非包含特殊字符。

1️⃣ title - 文档标题

说明：设置文档的标题，会显示在文档页面顶部和浏览器标签页。

格式：

title: 文档标题
# 或
title: '文档标题'

示例：

title: 快速开始

效果：

  • 文档页面大标题显示为「快速开始」
  • 浏览器标签页标题显示为「快速开始」

2️⃣ description - 文档描述

说明：设置文档的简短描述，会显示在文档页面的元信息卡片中。

格式：

description: 文档描述内容
# 或
description: '文档描述内容'

示例：

description: Astro温馨清新极简个人博客 - 「纸鸢」

效果：

  • 在元信息卡片顶部显示描述文本
  • 用于 SEO 优化

3️⃣ url - 自定义访问路径

说明：自定义文档的访问 URL，不设置则使用默认文件路径。

格式：

url: /custom-path
# 或
url: '/custom-path'

示例：

url: /quick-start

效果：

  • 文件路径：doc/快速开始.md
  • 默认访问链接：/快速开始
  • 自定义后访问链接：/quick-start

支持多级路径：

url: /docs/guide/faq

4️⃣ cover - 封面图片

说明：设置文档的封面图片，会显示在首页【最新文档】板块的文章卡片中。

格式：

cover: /图片路径
# 或
cover: '/图片路径'

示例：

cover: /assets/zhiyuan/gura.avif

效果：

  • 首页文章卡片显示封面图
  • 建议尺寸：16:9 比例，宽度 800px 以上

支持的图片格式：

  • .jpg / .jpeg
  • .png
  • .avif
  • .webp

5️⃣ date - 发布日期

说明：设置文档的发布日期，用于排序和显示。

格式：

date: YYYY-MM-DD
# 或
date: 'YYYY-MM-DD'

示例：

date: 2026-04-01

效果：

  • 文档页面显示发布日期
  • 首页文章按日期倒序排列（最新的在前）

6️⃣ tags - 标签

说明：为文档添加标签，支持多种分隔符格式。

格式：

# 顿号分隔（推荐中文场景）
tags: 标签1、标签2、标签3

# 逗号分隔
tags: 标签1, 标签2, 标签3

# 中文逗号分隔
tags: 标签1，标签2，标签3

# 混合分隔
tags: Astro、Vue,博客，纸鸢

# 数组格式
tags: [标签1, 标签2, 标签3]
# 或
tags: ['标签1', '标签2', '标签3']

示例：

tags: Astro、Vue、博客

效果：

  • 文档页面元信息卡片显示标签
  • 首页文章卡片显示标签

7️⃣ category - 分类

说明：设置文档的分类，用于首页文章筛选。

可选值：

  • tech - 技术
  • tutorial - 教程
  • notes - 笔记
  • life - 随笔

格式：

category: 分类名称
# 或
category: '分类名称'

示例：

category: 分类名称

效果：

  • 首页可按分类筛选文章
  • 文档页面显示分类标签

默认值：tech

8️⃣ readTime - 阅读时间

说明：设置预计阅读时间，不设置则自动计算。

格式：

readTime: X 分钟
# 或
readTime: 'X 分钟'

示例：

readTime: 5 分钟

自动计算规则：

  • 按每分钟 300 字计算
  • 向上取整
  • 示例：1500 字 → 5 分钟

效果：

  • 文档页面显示阅读时间
  • 首页文章卡片显示阅读时间

📦 完整表头示例

推荐写法（不使用引号）

---
title: 快速开始
description: Astro温馨清新极简个人博客 - 「纸鸢」
url: /quick-start
cover: /assets/zhiyuan/gura.avif
date: 2026-04-01
tags: Astro、Vue、博客
category: tutorial
readTime: 5 分钟
---

传统写法（使用引号）

---
title: '快速开始'
description: 'Astro温馨清新极简个人博客 - 「纸鸢」'
url: '/quick-start'
cover: '/assets/zhiyuan/gura.avif'
date: '2026-04-01'
tags: ['Astro', 'Vue', '博客']
category: 'tutorial'
readTime: '5 分钟'
---

📝 最小配置示例

如果只设置标题：

---
title: 我的文档
---

其他字段会自动处理：

  • 字数：自动计算
  • 阅读时间：根据字数自动计算
  • 日期：使用文件创建日期

🎯 配置优先级

  1. 手动配置 > 自动计算

    • 如果设置了 readTime，使用设置的值
    • 如果没有设置，自动根据字数计算

  2. 自定义 URL > 默认路径

    • 如果设置了 url，使用自定义路径
    • 如果没有设置，使用文件路径作为 URL

  3. 封面图 > 默认占位符

    • 如果设置了 cover，显示封面图
    • 如果没有设置，显示文档图标占位符

💡 最佳实践

  1. 标题：简洁明了，20字以内
  2. 描述：一句话概括文档内容，50字以内
  3. 封面图：使用 16:9 比例的高质量图片
  4. 标签：3-5 个相关标签，便于分类检索
  5. 分类：根据内容选择合适的分类
  6. 日期：保持格式统一 YYYY-MM-DD
  7. 引号使用：值中不含特殊字符时，建议不使用引号，更简洁

⚠️ 需要使用引号的情况

以下情况建议或必须使用引号包裹值：

  1. 值包含冒号：description: '注意: 这是重要提示'
  2. 值包含井号：title: '教程 #1'
  3. 值以特殊字符开头：title: '@用户名'
  4. 值包含换行：多行文本
  5. 值前后有空格：title: ' 标题 '

🔟 额外说明

titleIcon - 标题图标

说明：设置文档标题左侧显示的图标，默认不显示。

格式：

titleIcon: 🌟
# 或
titleIcon: '🌟'

示例：

titleIcon: 🌟

效果：

  • 文档页面标题左侧显示设置的图标
  • 不设置则不显示任何图标

常用图标推荐：

  • 🌟 星星
  • 📄 文档
  • 📝 笔记
  • 🎯 目标
  • 💡 提示
  • 🔧 工具
  • 📚 书籍
  • 🚀 火箭

🕊️ 白木 原创开发 🔗 gl.baimu.live