一句话理解 Obsidian#
Obsidian 就是一个 Markdown 编辑器：左边管理文件，中间写内容，右边预览效果。默认情况下笔记只保存在本地，就是一个普通的 .md 文件。
本站所有文章都放在 content/ 文件夹里，所以用 Obsidian 打开 content/ 这个文件夹就可以开始写了。
第一次打开#
- 打开 Obsidian。
- 点 Open folder as vault（打开文件夹作为仓库）。
- 选择本项目的
content文件夹，不要选项目根目录。 - 如果弹出“是否信任作者”，点信任。
打开后，左侧文件列表里应该能看到 posts、about.md 等文件。
先做两个设置（只做一次）#
打开左下角齿轮 → Files and links（文件与链接）。
- 关闭
Use [[Wikilinks]]Obsidian 默认用[[笔记名]]这种写法链接笔记，但 Hugo 不认识它，发布后只会原样显示文字。关掉后，Obsidian 会使用标准 Markdown 链接。 - 把新附件默认位置改成“当前文件所在文件夹” 即 Default location for new attachments → Same folder as current file。这样拖进来的图片会和笔记放在一起，Hugo 才能找到它。
写第一篇笔记#
目录结构#
每篇文章占用一个文件夹：
content/posts/my-first-note/
└── index.md网址由 frontmatter 里的 slug 决定，建议和文件夹同名：slug: "my-first-note" 对应 /posts/my-first-note/。所以文件夹名和 slug 都请用「英文小写 + 连字符」，不要用中文和空格。如果漏写 slug，Hugo 会拿标题当网址，中文标题就会变成一长串编码。
在 Obsidian 里新建#
- 在左侧
posts上右键 → New folder（新建文件夹），命名为my-first-note。 - 在刚建好的文件夹上右键 → New note（新建笔记），命名为
index。 - 打开
index.md，把下面这段粘贴到文件最上面：
---
title: "我的第一篇笔记"
slug: "my-first-note"
date: 2026-10-30
draft: true
summary: "一句话说明这篇笔记写什么"
tags: ["随笔"]
categories: ["笔记"]
series: []
---字段说明：
| 字段 | 作用 | 建议 |
|---|---|---|
title | 网页上的标题 | 直接写中文 |
slug | 网址里的英文名 | 和文件夹名一致，如 my-first-note |
date | 发布日期 | 格式 YYYY-MM-DD |
draft | 是否草稿 | 写作时 true，发布时改 false |
summary | 列表页的一句话摘要 | 一句话即可 |
tags | 标签 | 没有就留 [] |
categories | 分类 | 没有就留 [] |
series | 系列名 | 没有就留 [] |
title、slug、date、draft 建议一定保留，其他字段可以删。
Obsidian 会把这段显示成一张“属性”表格，这是正常的。如果想直接看原始文本，可以在 设置 → 编辑器 → 文档属性 里切换成“源码”模式。
- 在属性下面空一行，开始写正文。
更省事的方式（可选）#
在项目根目录运行：
hugo new content posts/my-first-note/index.md会自动生成文件夹和带 frontmatter 的 index.md，Obsidian 里会立刻出现。默认是 draft: true，记得改标题和日期，并补上 slug。
正文怎么写#
只记下面这些就够用了：
| 用途 | 写法 |
|---|---|
| 二级标题 | ## 二级标题 |
| 三级标题 | ### 三级标题 |
| 加粗 | **重点内容** |
| 无序列表 | - 第一项 |
| 有序列表 | 1. 第一步 |
| 引用 | > 引用内容 |
| 行内代码 | `hugo server` |
| 链接 | [OpenAI](https://openai.com) |
| 图片 |  |
代码块用三个反引号包起来，例如：
```python
print("hello")
```正文一般从
##开始，不要用#。因为 frontmatter 里的title已经是文章的一级标题了。
插入图片#
- 确认前面已经设置过“附件放当前文件夹”。
- 直接把图片拖进正在编辑的笔记，或者复制图片后粘贴。
- Obsidian 会自动把图片存到
index.md旁边，并插入一行。
|想截什么|快捷键|说明|
|---|---|---|
|整个屏幕|Shift + Command + 3|直接保存整屏截图|
|选定区域|Shift + Command + 4|拖选区域，松开即截图|
|某个窗口|Shift + Command + 4，再按 空格|指针变相机，点窗口即可|
|截图工具栏|Shift + Command + 5|可选区域、窗口、录屏、定时器等|
- **取消截图**：按 **Esc**。
- **复制进剪贴板**：在上述快捷键里多加一个 **Control**，比如 `Control + Shift + Command + 4`，就不会生成桌面文件。
默认截图会保存在**桌面**，文件名类似 `Screen Shot [日期] [时间].png`。最终目录长这样：
content/posts/my-first-note/
├── index.md
└── photo.png不要手写 ![[photo.png]]，站点上不会显示。关闭 Wikilink 后，Obsidian 会自动使用标准写法。
标签和搜索#
- 标签写在 frontmatter 的
tags里，例如tags: ["Agent", "RAG"]。站点会自动生成标签页面。 - 搜索所有笔记：
Cmd + Shift + F（Windows 是Ctrl + Shift + F）。 - 快速打开某篇笔记：
Cmd + O（Windows 是Ctrl + O），输入文件夹名即可。
本地预览与发布#
写作期间保持 draft: true，草稿不会出现在正式站点。
本地预览：
hugo server -D然后打开 http://localhost:1313。-D 表示包含草稿，去掉就只能看到已发布的文章。
准备发布时：
- 把 frontmatter 里的
draft: true改成draft: false。 - 运行
hugo --gc --minify重新构建。 - 把改动提交到 Git。
目前还没有自动部署，构建结果在
public/，由服务器上的 nginx 发布。
笔记之间互相链接（可以先跳过）#
Obsidian 的 [[另一篇笔记]] 在站点上不会生效。如果确实要链接，用标准 Markdown：
[另一篇笔记](/posts/other-note/)注意地址写的是文章网址，不是文件路径。这种链接在 Obsidian 里可能点不开，但发布后可以正常跳转。新手可以暂时不写站内链接。
常见问题#
- 左侧文件列表里全是
index：正常。本站每篇笔记都叫index.md，靠文件夹名区分，看文件夹名就行。 - 图片在 Obsidian 里能看，网站上不显示：检查图片是否和
index.md在同一个文件夹，以及有没有使用![[...]]写法。 - 改了内容网站没变化：本地
hugo server会自动刷新；线上需要重新构建并发布。 - 文件夹能用中文名吗：不建议。文件夹名就是网址，中文会变成一长串编码，也不方便分享。
.obsidian文件夹是什么：Obsidian 的本地设置，Hugo 会忽略，不影响站点。- 忘了 frontmatter 怎么写：复制任意一篇现有笔记，或者用
hugo new content生成。
五个动作小结#
- 用 Obsidian 打开
content/文件夹。 - 在
posts下新建英文文件夹。 - 在文件夹里新建
index.md。 - 顶部粘贴 frontmatter，正文用 Markdown 写。
- 写完把
draft改成false，预览、构建、提交。