这是在 Mizuki 博客系统中创建文章的推荐方法。这种方法更适合复杂文章，特别是包含大量图片或其他资源的场景。它非常适合希望不依赖外部图床、并优雅管理本地资源的用户。
创建文章
- 在
src/content/posts目录下创建一个新的文件夹，文件夹名建议具有描述性，例如my-complex-post。 - 在新建文件夹中创建
index.md。 - 在
index.md中添加 frontmatter（前置元数据）。其中title和description为必填字段。
---title: Markdown Tutorialpublished: 2025-01-20pinned: truedescription: A simple example of a Markdown blog post.tags: [Markdown, Blogging]category: ExampleslicenseName: "Unlicensed"author: emn178sourceLink: "https://github.com/emn178/markdown"draft: falsedate: 2025-01-20image: "./cover.png"pubDate: 2025-01-20permalink: "encrypted-example"---Frontmatter 字段详解
frontmatter 支持的常见字段如下。
必需字段
title：文章标题（必需）description：文章描述（必需）
发布相关
published：文章发布日期，格式建议YYYY-MM-DDpubDate：发布时间（语义与published接近）date：文章创建日期draft：是否草稿，true为草稿，false为正式发布permalink：自定义固定链接
内容分类
tags：标签数组，用于标记文章主题category：文章分类，用于组织内容pinned：是否置顶，true表示置顶
作者与来源
author：作者名licenseName：许可证名，如MIT、CC BY 4.0sourceLink：文章来源链接（如 GitHub 仓库）
图片设置
image：封面图路径
在 frontmatter 下方编写正文，使用标准 Markdown 语法即可。
Markdown 学习资源
如果你还不熟悉 Markdown，建议先补齐基础语法。
- 推荐学习地址：菜鸟教程 - Markdown 教程
建议先掌握这些内容：
- 标题、段落、换行
- 字体样式（粗体、斜体等）
- 列表、链接、图片
- 代码块、表格
- 常见扩展语法
掌握以上内容后，就可以顺畅地编写结构清晰的博客文章。
Mizuki Markdown 扩展语法
除了标准 Markdown，Mizuki 还支持仓库卡片、提示框和折叠剧透。以下示例同时提供源码和实际展示，方便直接复制使用。
一、GitHub 仓库卡片（GitHub Repository Cards）
仓库卡片会在页面加载时通过 GitHub API 获取仓库实时信息。
语法格式
::github{repo="用户名/仓库名"}repo 参数必填，格式为 GitHub 用户名/仓库名称。
使用示例
::github{repo="matsuzaka-yuki/Mizuki"}二、提示框（Admonitions）
提示框用于突出显示不同重要程度的信息，支持以下 5 种预设类型：
| 类型 | 语法标识 |
|---|---|
| 说明 | note |
| 技巧 | tip |
| 重要 | important |
| 警告 | warning |
| 注意（谨慎） | caution |
基础语法
将 类型标识 替换为上表中的标识，内容支持换行：
:::类型标识提示框内容（支持换行）:::以下是各类型的实际展示：
NOTE这是说明提示框，用于补充背景信息。
TIP这是技巧提示框，用于分享实用建议。
IMPORTANT这是重要提示框，用于强调需要关注的信息。
WARNING这是警告提示框，用于提醒潜在问题。
CAUTION这是注意提示框，用于提醒需要谨慎处理的操作。
自定义标题
在类型标识后添加方括号，可以修改提示框的默认标题：
:::note[我的自定义标题]这是一个带有自定义标题的说明提示框。:::我的自定义标题这是一个带有自定义标题的说明提示框。
GitHub 兼容语法
也可以使用 GitHub 风格的提示框语法：
> [!NOTE]> GitHub 语法的说明提示框。> 支持多行内容。
> [!TIP]> GitHub 语法的技巧提示框。NOTEGitHub 语法的说明提示框。 支持多行内容。
TIPGitHub 语法的技巧提示框。
三、折叠剧透（Spoiler）
剧透内容默认隐藏，悬停或点击时显示，内容支持 Markdown 格式。
语法格式
:spoiler[剧透内容（可包含 Markdown 语法）]使用示例
这是普通文本，剧透内容：:spoiler[被隐藏的**剧透内容**（支持粗体等 Markdown 语法）]！这是普通文本，剧透内容：
更多说明可参考 Mizuki 自定义 Markdown 文档。
Frontmatter 最佳实践
1. 日期格式
统一使用 ISO 8601：
published: 2025-01-20date: 2025-01-20pubDate: 2025-01-202. 标签与分类
- 标签要具体且相关，避免太宽泛。
- 分类用于更上层组织，通常比标签更宽。
tags: [Vue.js, JavaScript, Frontend, Tutorial]category: Web Development3. 草稿管理
draft: truedraft: true：不在生产环境展示draft: false：正常发布
4. 许可证设置
常见可选值：
MITApache-2.0CC BY 4.0CC BY-SA 4.0Unlicensed
5. 图片路径
文件夹方案推荐使用相对路径：
image: "./cover.jpg"完整示例
---title: "React Hooks 深度解析"published: 2025-01-20pinned: truedescription: "全面解析 React Hooks 的使用方法和最佳实践，包含大量代码示例和图片说明。"tags: [React, JavaScript, Hooks, Frontend]category: "Web Development"licenseName: "MIT"author: "李四"sourceLink: "https://github.com/lisi/react-hooks-guide"draft: falsedate: 2025-01-20image: "./react-hooks-cover.png"pubDate: 2025-01-20---
# React Hooks 深度解析
在这篇文章中，我们将深入探讨 React Hooks...预览文章
保存文件后，可在浏览器预览文章。将文件夹名拼接到预览 URL 末尾即可。
例如：本地开发地址为 http://localhost:4321/，文件夹名为 my-complex-post，则访问：
http://localhost:4321/posts/my-complex-post
如果文章尚未创建或文件夹名错误，页面会返回 404。预览失败时，可结合控制台输出进行排查。
链接到文章
在其他页面中可使用标准 HTML 链接：
<a href="/posts/my-complex-post/">我的复杂文章</a>确保 href 指向正确的文章路径。
小贴士：图片优化建议
- 优先使用
webp或压缩后的jpg/png，平衡清晰度与加载速度。 - 统一封面命名（如
cover.png），便于批量维护。 - 图多的文章建议按主题分子目录，如
images/intro、images/demo。 - 发布前检查失效图片路径，避免出现 404。
如果这篇文章对你有帮助，欢迎分享给更多人！
部分信息可能已经过时