这篇文章同时是两样东西：一份完整的 Daybook 内容演示，以及一份可以照着操作的笔记编写教程。原有的图注、提示块、折叠块、Mermaid、画廊和外部嵌入示例都保留在下方；每个部分先给出写法，再展示发布后的效果。
建议阅读顺序是：先看“最小笔记”了解文件结构，再按各章节复制语法，最后用文末模板新建自己的笔记。
1. 先创建一篇最小笔记
文件放在 Vault 的 notes/ 目录下，例如：
notes/学习/我的第一篇笔记.md
文件顶部写 YAML frontmatter：
---
title: 我的第一篇笔记
date: 2026-09-19
summary: 用一句话说明这篇笔记解决什么问题。
tags:
- 学习
draft: true
---
第二个 --- 之后才是正文。title、date 和 draft 最重要：draft: true 不会发布，确认内容无误后改为 false。
2. 用标题、段落和行内格式组织内容
正文建议从二级标题 ## 开始，三级标题 ### 用于拆分一个小问题：
## 二级标题
这一段先说明结论，再补充原因。
### 三级标题
这一节只讨论一个小问题。
段落之间要留一个空行；文字可以使用 加粗、斜体、删除线、行内代码，也可以插入 站内链接 或 外部链接。
3. 列表、任务和引用
- 无序列表
- 缩进表示子项
1. 第一步
2. 第二步
- [x] 已完成的任务
- [ ] 尚未完成的任务
> 先写结论，再写证据。
实际效果：
- 无序列表
- 缩进表示子项
- 第一步
- 第二步
- 已完成的任务
- 尚未完成的任务
先写结论，再写证据。
4. 表格和代码块
表格适合整理参数、实验结果和验收标准：
| 字段 | 作用 |
| --- | --- |
| `title` | 文章标题 |
| `date` | 发布日期 |
| `tags` | 标签数组 |
实际效果：
| 字段 | 作用 |
|---|---|
title |
文章标题 |
date |
发布日期 |
tags |
标签数组 |
代码块用三个反引号包住，并在开头写语言名称：
```cpp
#include <iostream>
int main() {
std::cout << "Hello, Daybook!" << std::endl;
}
```
实际效果：
#include <iostream>
int main() {
std::cout << "Hello, Daybook!" << std::endl;
}
5. 图注、图片和附件
使用标准 Markdown 图片语法即可生成图注：
普通 alt 会显示为图注；在 alt 前加 _ 或留空，可以隐藏图注。
实际效果：
Vault 内的附件可以使用 Obsidian embed：
![[attachments/picture/avatar.jpg]]
![[attachments/picture/avatar.jpg|center|480]]
![[attachments/pdf/paper.pdf]]
附件路径尽量写完整；同名文件较多时不要只写文件名。大体积音频和视频更适合放到 R2，再在正文中使用远程地址。
6. 提示块
使用 GitHub/Obsidian 语法 > [!TYPE] 或 Daybook 三冒号语法 :::type 创建提示块。支持 note、tip、important、warning、caution：
语法
> [!NOTE]
> 即使快速浏览，也值得读者留意的信息。
> [!TIP]
> 可以帮助读者更轻松完成操作的建议。
> [!IMPORTANT]
> 任务成功所需的关键信息。
:::warning
由于存在潜在风险，需要立即关注的内容。
:::
:::caution
某些操作可能带来的负面后果。
:::
:::note[自定义标题]
这是一个自定义标题的提示块。
:::
效果
Note
即使快速浏览，也值得读者留意的信息。
可以帮助读者更轻松完成操作的建议。
任务成功所需的关键信息。
由于存在潜在风险，需要立即关注的内容。
某些操作可能带来的负面后果。
这是一个自定义标题的提示块。
Obsidian 风格的展开状态
> [!note]
> A short note.
> [!warning]- 默认折叠
> 点击标题展开。
> [!tip]+ 默认展开
> 仍然可以手动收起。
实际效果：
A short note.
默认折叠
点击标题展开。
默认展开
仍然可以手动收起。
7. 折叠块
需要隐藏较长的补充说明时，使用 :::fold[title]：
:::fold[使用提示]
如果不是所有读者都需要，可以把详细推导、补充代码或背景资料放进来。
:::
实际效果：
使用提示
如果不是所有读者都需要，可以把详细推导、补充代码或背景资料放进来。
8. Mermaid 图表
用 mermaid 标记代码块，Daybook 会把流程图渲染出来：
```mermaid
flowchart LR
A[写 Markdown] --> B[Daybook 构建]
B --> C[发布为静态页面]
```
实际效果：
flowchart LR
A[写 Markdown] --> B[Daybook 构建]
B --> C[发布为静态页面]9. 画廊
使用 :::gallery 创建可水平滚动的图片画廊：
:::gallery
:::
实际效果：
10. Obsidian 双链和内容嵌入
发布后，站内链接最好使用稳定的 /notes/ 地址：
[阅读 Markdown 总览](/notes/markdown-syntax/)
也可以使用 Obsidian 双链指向另一篇笔记。双链前加 ! 表示嵌入内容；长文建议只链接过去，避免当前页面变得过长。
11. 外部内容组件
Daybook 支持用独占一行的 directive 嵌入外部服务：
::github{repo="StatIndet/daybook"}
::youtube{id="9pP0pIgP2kE"}
::bilibili{id="BV1sK4y1Z7KG"}
::spotify{url="https://open.spotify.com/track/0HYAsQwJIO6FLqpyTeD3l6"}
::tweet{url="https://x.com/hachi_08/status/1906456524337123549"}
::codepen{url="https://codepen.io/jh3y/pen/NWdNMBJ"}
GitHub 仓库效果
Loading repository data...
视频效果
Spotify 效果
X 推文效果
CodePen 效果
外部服务不可用时，正文仍应保留文字说明，不能把核心结论只放在嵌入卡片里。
12. 远程媒体
图片、音频、视频和 PDF 可以使用统一的媒体 directive：
::image{url="https://example.com/picture.jpg" width="720" caption="示例图片"}
::audio{url="https://example.com/audio.mp3" loop="true"}
::video{url="https://example.com/video.mp4" muted="true" controls="true"}
::pdf{url="https://example.com/paper.pdf" height="720"}
::music{url="https://example.com/music.mp3" title="曲名" artist="艺术家"}
公开页面只使用自己拥有、获授权或可以合法再分发的媒体。URL 能访问不代表拥有再分发权；大文件优先放 R2。
13. 一套可重复的写作流程
- 先写标题、日期和一句摘要；
- 用二级标题拆成几个可以独立复习的小问题；
- 每节先写结论，再补充过程、代码或证据；
- 用表格整理参数，用代码块保留可复制命令；
- 只有确实有帮助时才加入图片、图表和外部嵌入；
- 本地预览后检查链接、图片、代码围栏和提示块；
- 确认内容完整后把
draft设为false，再提交发布。
14. 发布前快速检查
最常见的问题不是 Markdown 语法不会写，而是 frontmatter、文件路径和媒体地址不一致。
- frontmatter 两端都有
---，YAML 缩进正确； title、date已填写，公开文章的draft为false；- 标题层级从
##开始，代码块和三冒号围栏成对； - 图片、附件和嵌入地址实际可访问；
- 文件移动或改名后，检查站内链接是否仍然指向原路径；
- 发布后在笔记列表、归档和图谱中确认文章已经出现。
15. 可以直接复制的练习模板
---
title: 我今天学到的一个问题
date: 2026-09-19
summary: 用一句话写出这篇笔记的结论。
tags:
- 学习
draft: true
---
## 结论
先用两三句话写清楚答案。
## 为什么
补充推理过程、实验数据或引用资料。
## 示例
```text
把一个最小、可复制的例子放在这里。
```
## 下一步
- [ ] 还有什么需要验证？
- [ ] 哪个链接或附件需要补上？
写完并检查无误后，把 draft: true 改为 draft: false，再提交发布。
验收结论
完成一次构建后，应从普通 Markdown、图注、提示块、折叠块、Mermaid、画廊到外部嵌入逐项检查。外部服务不可用时，页面应保留清晰的降级提示，不得遮挡正文或破坏其他组件布局。