参考篇：Obsidian Markdown 发布效果演示

这篇文章用于展示 Obsidian Markdown 发布到个人知识网站后的实际效果。

它面向需要长期写技术笔记、科研记录、实验过程、论文阅读笔记和项目文档的人。

每一节都包含两部分：

• 输入写法：在 Obsidian 或 Markdown 文件中怎么写
• 发布效果：网站最终会如何展示

这能帮助读者直观看到：内容不需要写进复杂后台，只要保存为 Markdown，就可以发布成结构化、可检索、可长期维护的个人网站。

1. 文章 Frontmatter 元数据

输入写法：

---
title: "PVE 网络规划"
slug: pve-network-planning
description: "记录一次 Homelab 网络规划实践。"
publishedAt: 2026-07-27
tags:
  - Homelab
  - PVE
  - Network
draft: false
series:
  id: homelab-build
  title: "Homelab 建设手记"
  description: "从硬件、虚拟化、网络到服务部署的长期建设记录。"
  order: 3
---

发布效果：

网站会根据这些字段自动生成文章标题、摘要、发布时间、标签、系列关系、上一篇/下一篇和相关文章。

2. 标题层级

输入写法：

## 二级标题

### 三级标题

#### 四级标题

发布效果：

二级标题示例

二级标题会进入文章目录，是文章的主要结构。

三级标题示例

三级标题会在目录中缩进展示，适合表达小节。

四级标题示例

四级标题会进一步缩进，适合复杂技术文章中的细分层级。

3. 列表

输入写法：

- 本地 Markdown 保存
- Obsidian 写作
- 网站发布
- 全文搜索

发布效果：

• 本地 Markdown 保存
• Obsidian 写作
• 网站发布
• 全文搜索

有顺序的步骤也可以这样写：

1. 打开 Obsidian
2. 编写文章
3. 点击发布
4. 网站更新

发布效果：

1. 打开 Obsidian
2. 编写文章
3. 点击发布
4. 网站更新

4. 引用

输入写法：

> 好的知识系统不会锁住内容，而是帮助内容长期流动。

发布效果：

好的知识系统不会锁住内容，而是帮助内容长期流动。

5. Obsidian Callout

输入写法：

> [!NOTE] 说明
> 这里是一段说明信息，适合补充背景。

发布效果：

[!NOTE] 说明 这里是一段说明信息，适合补充背景。

输入写法：

> [!TIP] 建议
> 把长期内容保存为 Markdown，可以降低迁移成本。

发布效果：

[!TIP] 建议 把长期内容保存为 Markdown，可以降低迁移成本。

输入写法：

> [!WARNING] 注意
> 公开发布前，需要确认文章里没有密钥、服务器地址或私人信息。

发布效果：

[!WARNING] 注意 公开发布前，需要确认文章里没有密钥、服务器地址或私人信息。

6. 表格

输入写法：

| 展示项 | 用途 | 价值 |
| --- | --- | --- |
| 标签 | 横向归类 | 找到同主题内容 |
| 系列 | 纵向组织 | 形成学习路线 |
| 搜索 | 全文检索 | 快速找回知识 |

发布效果：

展示项	用途	价值
标签	横向归类	找到同主题内容
系列	纵向组织	形成学习路线
搜索	全文检索	快速找回知识

长表格会在文章内部横向滚动，不会撑破页面。

7. 代码块和多语言语法高亮

输入写法：

```bash
pnpm run blog:check
pnpm run build
```

发布效果：

pnpm run blog:check
pnpm run build

代码块右上角会提供复制按钮，适合命令、配置和脚本示例。

不同语言会使用不同的语法高亮。

Bash 示例：

pnpm run blog:check
pnpm run build

TypeScript 示例：

type PostStatus = "draft" | "published";

interface PostMeta {
  title: string;
  tags: string[];
  status: PostStatus;
}

const canPublish = (post: PostMeta) =>
  post.status === "published" && post.tags.length > 0;

YAML 示例：

title: "科研记录"
tags:
  - Markdown
  - Research
draft: false

SQL 示例：

select title, published_at
from posts
where status = 'published'
order by published_at desc;

8. Mermaid 图表

输入写法：

```mermaid
flowchart LR
  A[Obsidian 写作] --> B[Markdown Vault]
  B --> C[内容校验]
  C --> D[静态构建]
  D --> E[个人网站]
```

发布效果：

图表加载中...

Mermaid 图表会懒加载渲染。加载过程中不会显示源码，只有渲染失败时才会显示源码作为兜底。

9. KaTeX 数学公式

行内公式输入写法：

质能方程可以写成 $E = mc^2$。

发布效果：

质能方程可以写成 $E = mc^2$。

块级公式输入写法：

$$
\int_0^1 x^2 \, dx = \frac{1}{3}
$$

发布效果：

$$\int_0^1 x^2 \, dx = \frac{1}{3}$$

多行公式输入写法：

$$
\begin{aligned}
f(x) &= (x + 1)^2 \\
     &= x^2 + 2x + 1 \\
f'(x) &= 2x + 2
\end{aligned}
$$

发布效果：

$$\begin{aligned} f(x) &= (x + 1)^2 \\ &= x^2 + 2x + 1 \\ f'(x) &= 2x + 2 \end{aligned}$$

长公式会在公式区域内部横向滚动，避免破坏文章排版。

10. 脚注

输入写法：

Markdown 的好处是内容长期可迁移。[^portable]

[^portable]: 这里的可迁移，指内容可以被其它静态站工具或 Markdown 编辑器继续读取。

发布效果：

Markdown 的好处是内容长期可迁移。¹

在文章中点击或悬停脚注编号，可以快速查看脚注内容。

11. 图片、附件和音视频

输入写法：

感叹号 + 方括号图片说明 + 小括号图片路径

发布效果：

图片会作为文章附件一起发布，并在正文中按文章宽度自适应展示。

如果使用 Excalidraw，可以保留源文件，同时导出 SVG 或 PNG 用于网页展示。这样既方便后续继续编辑，也能让读者直接看到图。

下载附件可以这样写：

[实验记录 PDF](./附件示例/实验记录.pdf)

如果这条链接单独成段，网页会把它展示成下载卡片。

实际附件示例：

CSV实验记录 CSV点击下载附件

音频可以这样写：

[访谈录音](./附件示例/interview.mp3)

如果这条链接单独成段，网页会把它展示成音频播放器。

外部视频可以这样写：

[演示视频](https://www.bilibili.com/video/BV1xx411c7mD/)

如果这条链接单独成段，网页会把它展示成外部视频卡片。本地视频文件暂不建议放进博客目录，避免内容仓库变得过重。

12. 内容组织效果

除了正文格式，本站还会读取文章元数据，生成额外阅读入口：

• 标签页：聚合同主题文章
• 系列页：展示一条完整阅读路线
• 文章目录：展示当前文章结构
• 关联阅读：点击标签后查看相关文章
• 全文搜索：按关键词找回文章

也就是说，只需要维护 Markdown，网站会把这些内容整理成更适合阅读和检索的形态。

13. 一句话总结

输入端保持简单：

Markdown + Frontmatter + 附件

发布端变得完整：

文章页 + 标签页 + 系列页 + 搜索 + 图表 + 公式 + 关联阅读

这就是本站希望提供的核心体验：内容继续保存在自己手里，同时拥有一个清晰、稳定、可长期演进的个人网站。

Footnotes

1. 这里的可迁移，指内容可以被其它静态站工具或 Markdown 编辑器继续读取。 ↩