Daybook 以 Goldmark 解析 Markdown，并在其上加入 GFM、Obsidian 兼容语法和少量面向博客的扩展。日常写作仍然可以从标准 Markdown 开始；只有需要双链、嵌入或特殊组件时，才需要额外语法。

文章元数据本身不属于 Markdown 正文。它写在文件顶部的 YAML frontmatter 中，详见 文章 Frontmatter。

阅读路径

先掌握标准 Markdown，再按需阅读 Obsidian 双链、媒体嵌入和 Daybook 容器。每个小节都先给可复制的源代码，再说明渲染结果与使用边界；站点级配置放在文末，避免把文章元数据和正文语法混在一起。

标准 Markdown 与 GFM

标题与文本

#### 标题层级示例

下面的示例展示二级、三级标题在源文件中的写法：

```markdown
## 二级标题
### 三级标题

加粗 斜体 删除线 inline code


Daybook 的文章目录收集二级到四级标题。普通链接、自动链接、水平线和引用块都按常见 Markdown 方式书写。

### 列表与任务

```markdown
- Item
  - Nested item

1. First
2. Second

- [x] Done
- [ ] Todo

表格

| Field | Meaning |
| --- | --- |
| `title` | Article title |
| `date` | Publication date |

脚注

源 Markdown：

Daybook 使用 Goldmark 解析正文。[^goldmark]

[^goldmark]: 脚注会被集中渲染到文章末尾。

实际效果：

Daybook 使用 Goldmark 解析正文。1

链接

源 Markdown：

[Daybook on GitHub](https://github.com/StatIndet/daybook)

<https://github.com/StatIndet/daybook>

实际效果：

Daybook on GitHub

https://github.com/StatIndet/daybook

代码块

为 fenced code block 标注语言即可启用语法高亮：

```go
package main

import "fmt"

func main() {
    fmt.Println("hello")
}
```

^64da35

渲染后的代码块带有复制按钮。无语言标记的代码块仍保持普通等宽排版。

图片与图注

标准 Markdown 图片可以直接使用远程 URL：

![A caption](https://example.com/image.jpg)

Daybook 会把普通 alt 作为图注。若 alt 以 _ 开头，或 alt 为空，则不显示图注：

![_Alt text without a visible caption](https://example.com/image.jpg)
![](https://example.com/image.jpg)

Vault 内附件更适合使用 Obsidian embed，详见本文“附件与远程媒体”一节。

Obsidian 双链

Daybook 会解析 Obsidian 的 [[...]] 语法。目标可以使用文章标题、slug 或 Markdown 文件名；也可以追加别名、小节或块 ID。

链接文章

源 Markdown：

[静夜思](/notes/%E9%9D%99%E5%A4%9C%E6%80%9D/)
[English-only Shakespeare example](/notes/Shakespeare/)

实际效果：

静夜思

English-only Shakespeare example

链接文章小节

源 Markdown：

[查看代码排版](/notes/typography-test/#4.%20%E8%A1%8C%E5%86%85%E4%BB%A3%E7%A0%81%E4%B8%8E%E4%BB%A3%E7%A0%81%E5%9D%97%E6%B5%8B%E8%AF%95)

如果目标文章中不存在这个标题，Daybook 会在构建阶段输出 obsidian/missing-heading 警告。

块 ID

在文本块末尾添加 ^block-id，即可让这个块成为可嵌入目标。

源 Markdown：

这是一个可以被精确嵌入的段落。 ^syntax-block-demo

实际效果：

这是一个可以被精确嵌入的段落。 ^syntax-block-demo

当前 Daybook 主要将 block ID 用于 ![[note#^block-id]] 块级嵌入；普通 Wikilink 暂不生成精确的块锚点跳转。块 ID 只使用字母、数字与连字符最稳妥。

Obsidian 页面与局部嵌入

在双链前添加 !，Daybook 会把目标内容直接嵌入当前文章。

整篇文章嵌入

源 Markdown：

![静夜思](/notes/%E9%9D%99%E5%A4%9C%E6%80%9D/)

实际效果：

静夜思
静夜思

小节嵌入

源 Markdown：

![typography-test](/notes/typography-test/#%E5%B8%B8%E8%A7%81%E5%BC%BA%E8%B0%83)

实际效果：

typography-test
typography-test

块级嵌入

源 Markdown：

![markdown-syntax](/notes/markdown-syntax/#%5Esyntax-block-demo)

实际效果：

markdown-syntax
markdown-syntax

Daybook 会限制嵌入递归深度，并检测循环引用，避免两篇文章相互嵌入后无限展开。

Obsidian 高亮与注释

高亮：

==important text==

渲染为 important text。

注释使用 %% 包裹。它们保留在 Markdown 源文件中，但不会出现在最终 HTML：

%% 这段内容只留在源文件中。 %%

代码和数学内容会先被保护，不应因为其中出现 == 或 %% 而被当作高亮或注释。

Callout

Obsidian 风格：

> [!note]
> A short note.

> [!warning]- 默认折叠
> 点击标题展开。

> [!tip]+ 默认展开
> 仍然可以手动收起。

常用类型包括 note、tip、important、warning、caution、abstract、info、todo、success、question、failure、danger、bug、example 与 quote。faq、hint、tldr 等常见别名也会映射到对应类型。

Daybook 还支持容器写法：

:::note[自定义标题]
这里仍然可以写 **Markdown**。
:::

Daybook 容器

折叠块

:::fold[展开查看]
这里可以放较长的补充内容。
:::

画廊

:::gallery
![Image one](https://example.com/1.jpg)
![Image two](https://example.com/2.jpg)
:::

Mermaid

使用 mermaid 或 {mermaid} 作为代码块语言：

```mermaid
graph LR
    A[Markdown] --> B[Daybook]
    B --> C[Static HTML]
```

数学公式

含有数学公式的文章应在 frontmatter 中设置：

math: true

然后使用行内 $...$ 或块级 $$...$$ 数学语法。完整效果可查看 KaTeX 数学公式测试。

外部内容与媒体

Daybook 的 leaf directive 必须单独占一行，属性使用引号：

::github{repo="StatIndet/daybook"}
::youtube{id="9pP0pIgP2kE"}
::bilibili{id="BV1sK4y1Z7KG"}
::spotify{url="https://open.spotify.com/track/0HYAsQwJIO6FLqpyTeD3l6"}
::tweet{url="https://x.com/example/status/1234567890"}
::codepen{url="https://codepen.io/example/pen/example"}

图片、视频、音频、PDF 与音乐播放器分别使用 ::image、::video、::audio、::pdf 和 ::music，参数见下文“附件与远程媒体”。

如果想直接查看这些组件组合后的页面，可阅读 Markdown 扩展语法测试页。

附件与远程媒体

Daybook 对媒体只有一个判断：Vault 中的受支持文件按本地附件处理，正文显式写出的 HTTP(S) 资源按远程媒体处理。目录名不会改变这一规则，也不会自动把文件上传到 R2。

Vault 内附件

构建时会扫描并复制以下格式到 public/：图片（PNG、JPEG、GIF、WebP、AVIF、SVG）、音频 （FLAC、MP3、WAV、OGG、M4A）、视频（MP4、WebM、MOV）和 PDF。Obsidian 配置中的 attachmentFolderPath 可辅助解析链接。

![[attachments/picture/avatar.jpg]]
![[attachments/picture/avatar.jpg|center|480]]
![[attachments/pdf/paper.pdf]]
![[attachments/audio/example.flac]]

大型 Vault 建议写明确相对路径；同名附件有歧义时，Daybook 会给出警告而不会猜测。单文件接近 或超过 25 MiB 时不适合放入 Pages，宜转为对象存储或其他静态文件服务。

远程媒体 directive

远程资源可以来自 R2、S3、CDN、自建静态站点或其他可访问的 HTTP(S) 地址：

::image{url="https://static.example/picture.jpg" width="720" align="center" caption="示例"}
::pdf{url="https://static.example/paper.pdf" height="720" caption="论文"}
::audio{url="https://static.example/audio.flac" loop="true"}
::video{url="https://static.example/video.mp4" width="720" muted="true" loop="true"}
::music{url="https://static.example/music.flac" title="曲名" artist="艺术家" cover="https://static.example/cover.jpg" loop="true"}

::image 支持 url、alt、caption、width、align；::pdf 还支持 height； ::audio 支持 caption、width、align、autoplay、muted、loop；::video 支持 caption、height、poster、autoplay、muted、loop；::music 支持 title、artist、cover、loop。directive 必须独占一行，属性值使用引号。

公开部署时只使用自己拥有、获授权或可合法再分发的媒体；“能通过 URL 访问”不等于“获得了 再分发权”。大体积媒体优先放对象存储，正文保留远程 URL。

daybook.yaml 站点配置

daybook.yaml 位于 Vault 根目录，由 daybook build 读取。站点配置和文章 frontmatter 分工明确：前者描述全站资料、作者、SEO、评论、统计与分享模板，后者描述单篇文章标题、日期、 语言和正文。文件缺失或 YAML 语法错误会使构建直接失败。

site:
  name: {en: "My Daybook", zh: "我的笔记"}
  url: "https://example.com"
  startedAt: "2024-01-01"
  favicon: "assets/favicon.svg"
profile:
  author:
    name: "佚名"
    nameEn: "Author"
    logoText: "Author"
    avatar: "/attachments/picture/avatar.jpg"
    aboutUrl: "/about"
  social:
    - {type: github, url: "https://github.com/your-name"}
  slogan: {en: "A personal space.", zh: "记录思考与笔记。"}
seo:
  homeTitle: {en: "Notes", zh: "我的 Daybook"}
  homeDescription: {en: "Personal notes.", zh: "个人笔记。"}
comment:
  enabled: false
  provider: waline
  waline: {serverURL: "", lang: "zh-CN", pageSize: 10, commentSorting: latest, search: false, imageUploader: false}
stats: {enabled: true}
share: {text: '「{Title}」'}

常用字段约束

  • site.name、profile.slogan、seo.homeTitle 和 seo.homeDescription 可写 en/zh 多语言值；site.url 必须是以 http:// 或 https:// 开头的公开基础 URL，用于 canonical、 分享链接和 sitemap。
  • site.startedAt 建议使用 YYYY-MM-DD；favicon 相对 Vault 根目录，文件不存在会报错。
  • profile.author.avatar 可引用随构建发布的 Vault 图片；social 每项必须包含 type 与 url，不支持的类型会被跳过并警告。RSS 由 Daybook 自动添加，无需手动填入。
  • comment 当前使用 Waline。启用却没有 serverURL 时会警告并关闭；单篇 frontmatter 的 comment: true/false 可覆盖站点默认值。
  • stats.enabled 只控制站点配置，不会自动创建 Cloudflare D1 等后端资源；部署环境仍需提供 对应绑定。share.text 中的 {Title} 会替换成文章标题。

配置可在本地预览时把 site.url 设为本地地址，正式部署前改回最终域名。更改站点名称或评论 服务时只改 daybook.yaml，不必批量修改文章正文。

发布前验收

  • Markdown 文件顶部的 frontmatter 可被 YAML 解析，title 与 date 已填写；
  • 标题层级连续，代码围栏成对出现，表格分隔线完整；
  • 双链、附件和远程媒体在本地构建后没有新的未解析引用；
  • 公开文章不包含未授权媒体或不应公开的凭据。

  1. 脚注会被集中渲染到文章末尾。 ↩︎