Blog Markdown Format

博客 Markdown 格式规范

当处理博客文章的迁移、完善或生成时，必须遵循以下格式规范。

博客文件结构

博客文章存放在 src/content/blogs 目录下，按年份分类：

src/content/blogs/
├── 2024/
│   └── my-projects.md
├── 2025/
│   ├── simple-post.md              # 无资源的简单文章
│   └── blazwitcher/                # 有资源的文章（文件夹形式）
│       ├── index.md                # 文章内容
│       ├── hero-image.png          # 封面图片
│       ├── screenshot-1.gif        # 文章内引用的图片
│       └── demo.mp4                # 其他资源文件
└── 2026/
    └── ...

文件组织规则

1. 无资源的文章：直接使用 .md 文件，如 2024/my-projects.md
2. 有资源的文章：创建同名文件夹，文章命名为 index.md，资源文件放在同一目录下
3. 图片引用：使用相对路径 ./filename.png 引用同目录下的图片

迁移文章时的资源处理

从其他项目迁移博客文章时，必须同步处理资源文件：

1. 检查原文章中的所有图片和资源引用
2. 在 src/content/blogs/{年份}/ 下创建文章同名文件夹
3. 将原文章重命名为 index.md 并移入文件夹
4. 将所有引用的图片/资源文件复制到同一文件夹
5. 更新文章中的资源路径为相对路径 ./filename.ext

优化建议：迁移包含图片的文章时，建议先将原文章内容直接复制到目标文件夹下的 index.md，然后在此基础上进行修改，可有效减少 token 消耗。

外部图片链接处理：当文章中包含完整 URL 的图片链接（如 https://example.com/image.png）时，需要检查该链接是否可用。如果链接不可用（404、超时等），应直接删除该图片引用。

迁移时的容器语法转换

从 VuePress 等其他平台迁移文章时，需要将容器语法从空格分隔格式转换为方括号格式：

批量转换命令（可在终端执行）：

# 在博客目录下执行，将所有 VuePress 风格的容器语法转换为本博客支持的格式
find . -name "*.md" -exec sed -i '' -E 's/^:::[[:space:]]+(tip|warning|danger|info|details)([[:space:]]+(.*))?$/:::\1[\3]/g' {} \;
# 清理空方括号
find . -name "*.md" -exec sed -i '' -E 's/:::(tip|warning|danger|info|details)\[\]([[:space:]]*)?$/:::\1/g' {} \;

Frontmatter 格式

每篇博客文章必须包含以下 frontmatter 头部信息：

---
layout: "xx/BlogPost.astro"
title: "文章标题"
description: "文章描述，简要概括文章内容"
tags: ['标签1', '标签2']
pubDate: 'YYYY-MM-DD'
updatedDate: 'YYYY-MM-DD'
author: '作者名称'
authorHref: '作者链接'
heroImage: '/图片路径.jpg'
heroImageAlt: '图片描述'
---

字段说明

Markdown 语法规范

标题层级

• 使用 ## 作为文章内的一级标题（H2）
• 依次使用 ###、#### 等作为子标题
• 不要在文章内容中使用 #（H1），因为文章标题已在 frontmatter 中定义

图片

![图片描述](/图片路径.jpg)

引用块

普通引用：

引用内容 注意 可以在引用中使用 Markdown 语法

带出处的引用：

引用内容 — 出处^1

表格

代码块

使用三个反引号包裹代码，并指定语言：

const example = 'code';

支持的语言标识：html、css、javascript、typescript、python、go、bash、yaml、json 等。

列表

有序列表：

1. 第一项
2. 第二项
3. 第三项

无序列表：

• 列表项
• 另一项
• 再一项

嵌套列表：

• 父级项
  • 子级项
  • 子级项

特殊元素

• 缩写：<abbr title="全称">缩写</abbr>
• 下标：H<sub>2</sub>O
• 上标：X<sup>n</sup>
• 键盘按键：<kbd>CTRL</kbd>+<kbd>C</kbd>
• 高亮：<mark>高亮文本</mark>

脚注

这是一段带脚注的文本^2。

自定义容器

本博客支持类似 VuePress 的自定义容器语法，用于突出显示提示、警告等信息。

语法格式：

:::类型[标题] 内容 :::

注意：类型和 [ 之间不能有空格。

支持的容器类型：

示例：

提示容器（自定义标题）：

:::tip[带着问题看源码] 为什么每个 Vue 组件都可以访问到 this.$store？ :::

警告容器（使用默认标题）：

:::warning 这是一个需要注意的事项 :::

危险容器：

:::danger[危险操作] 此操作不可逆，请谨慎执行！ :::

可折叠详情容器：

:::details[点击展开] 这里是折叠的详细内容... :::

使用场景

当执行以下任务时，应调用此 skill：

1. 迁移博客文章：将其他格式的文章转换为本博客的 Markdown 格式
2. 完善博客文章：补充或修正现有文章的格式
3. 生成新博客文章：创建符合规范的新文章模板