写作指南#

受众：Mizuki-Content 内容仓作者（Astro + Mizuki 主题）。目标：最快写出一篇可发布文章，并掌握本框架的扩展语法（Admonitions、Mermaid、数学公式等）。

1. 最小可用文章#

在 posts/（或其子目录）创建 .md，写上 frontmatter + 正文。

1.1 最小 Frontmatter#

1
---
2
title: 标题
3
published: 2026-01-01
4
description: 简短描述
5
---

1.2 推荐模板#

1
---
2
title: "文章标题"
3
published: 2026-01-20
4
description: "简短的描述"
5
image: /images/posts/cover.jpg
6
tags: [标签1, 标签2]
7
category: Guides
8
# updated: 2026-01-21
9
# author: 作者名
10
# licenseName: "CC BY-NC-SA 4.0"
11
# sourceLink: "https://..."
12
# toc: true
13
# lang: zh-cn
14
# pinned: true
15
# encrypted: true
16
# password: "your-password"
17
draft: false
18
---

2. 文章放哪儿#

文章（Markdown）放在 posts/。
可以用子目录组织（推荐：目录文章便于放封面/附件）。

示例：

1
posts/
2
├─ my-post.md
3
└─ guide/
4
   └─ my-post/
5
      ├─ cover.png
6
      └─ index.md

3. Frontmatter 字段速查#

说明：字段以现有内容仓文档与示例为准；不同主题/版本可能会扩展更多字段。

3.1 常用字段#

字段	含义
`title`	文章标题
`published`	发布日期
`description`	文章摘要（列表页/SEO）
`tags`	标签数组
`category`	分类
`image`	封面图路径
`draft`	草稿（不会显示）
`pinned`	置顶

3.2 可选字段#

字段	含义
`updated`	更新日期
`author`	作者
`licenseName`	许可协议名
`sourceLink`	来源/引用链接
`keywords`	SEO 关键字
`toc`	是否显示目录
`lang`	语言（如 `zh-cn`/`en`/`ja`）

3.3 特殊：加密文章#

如需加密文章，设置 encrypted: true 并提供 password。

1
---
2
title: "私密文章"
3
published: 2024-01-01
4
description: "加密内容"
5
encrypted: true
6
password: "123456"
7
draft: false
8
---

4. 图片与资源#

4.1 封面图 `image` 三种写法#

image 字段支持 3 种路径规则：

https://... / http://...：外链图片
/...：映射到站点 public 根目录
./... 或普通相对路径：相对当前 md 文件

示例：

1
image: "https://example.com/cover.webp"  # 外链
2
image: "/images/posts/cover.jpg"         # public/images/posts/cover.jpg
3
image: "./cover.png"                    # 与当前 md 同目录

4.2 正文图片#

1
![图片描述](/images/posts/my-image.jpg)

推荐目录：images/posts/（可再按年份/专题分组）。

5. Markdown 基础#

如果你不熟悉 Markdown，建议先看仓库自带教程：

也可以在本文末尾的「延伸阅读」里继续查看更多示例与文档。

6. Mizuki/Astro 扩展语法（主题特有能力）#

这部分可直接复制示例使用。

6.1 提示块容器（Admonitions）#

支持类型：note tip important warning caution

1
:::note
2
提示内容
3
:::
4

5
:::tip
6
小技巧
7
:::

自定义标题：

1
:::note[自定义标题]
2
这里是带自定义标题的提示块。
3
:::

6.2 GitHub 提示块语法#

1
> [!NOTE]
2
> 这里是 NOTE 内容。
3

4
> [!TIP]
5
> 这里是 TIP 内容。

6.3 GitHub 仓库卡片#

1
::github{repo="matsuzaka-yuki/Mizuki"}

6.4 折叠（剧透）#

行内 spoiler 短代码：

1
这里有一段 :spoiler[被隐藏的 **内容**]！

6.5 Mermaid 图表#

使用 fenced code block，并指定语言为 mermaid：

graph TD A[开始] --> B[处理] B --> C[结束]

更多示例：Markdown Mermaid

6.6 数学公式（KaTeX）#

行内： $E = mc^2$
块级：

1
$$
2
\int_{a}^{b} f(x) \, dx
3
$$

6.7 视频嵌入（iframe）#

把平台提供的嵌入代码直接粘贴进 Markdown 即可。

1
<iframe
2
  width="100%"
3
  height="468"
4
  src="https://www.youtube.com/embed/5gIf0_xpFPI?si=N1WTorLKL0uwLsU_"
5
  title="YouTube video player"
6
  frameborder="0"
7
  allowfullscreen
8
></iframe>

更多示例：视频嵌入示例

7. 草稿与可见性#

如果文章不显示，优先检查：

draft: true：草稿不会显示
published 在未来：可能会被隐藏

示例：

1
---
2
title: Draft Example
3
published: 2024-01-11T04:40:26.381Z
4
draft: true
5
---

8. 常见问题排查#

8.1 封面图不生效#

如果使用 /...，确认该文件实际位于代码仓 public/ 下。
如果使用 ./cover.png，确认图片与 md 文件同目录。

8.2 Mermaid 不渲染#

必须是 fenced code block，且语言标记必须为 mermaid。

8.3 公式不渲染#

使用 $...$ 或 $$...$$，不要把公式包进普通代码块。

9. 延伸阅读#

说明：以下链接均为内容仓内文件，点击可直接跳转。

9.1 指南#

9.2 示例#

Markdown Tutorial

L1ngg's Home