Obsidian 笔记库使用指南

本指南将帮助您设置和使用 Obsidian 作为 Astro Modular 博客的内容管理系统。

为什么选择 Obsidian？

Obsidian 是一个强大的知识管理工具，与 Astro Modular 完美配合：

Markdown 原生支持：所有内容都存储为纯文本 Markdown 文件
双向链接：使用 [[Wikilinks]] 在笔记之间创建连接
本地优先：您的数据保存在本地，完全掌控
插件生态：丰富的插件扩展功能
即时预览：实时查看 Markdown 渲染效果

设置 Obsidian 笔记库

1. 打开文件夹作为笔记库

启动 Obsidian
选择 “打开文件夹作为笔记库”
导航到项目中的 src/content/ 目录
选择该文件夹

2. 信任作者并启用插件

首次打开时，Obsidian 会询问是否信任该笔记库的作者：

点击 “信任作者和启用插件”
这将启用预配置的插件以获得最佳体验

3. 配置 Astro Modular Settings

笔记库包含一个名为 Astro Modular Settings 的自定义插件：

打开命令面板（Ctrl/Cmd + P）
搜索 “Astro Modular Settings”
使用向导配置您的博客设置
更改会自动保存到 src/config.ts

笔记库结构

src/content/
├── .obsidian/          # Obsidian 配置
├── posts/              # 博客文章
├── pages/              # 静态页面
├── projects/           # 项目展示
├── docs/              # 文档
└── special/           # 特殊页面（主页等）

创建内容

文章

在 posts/ 文件夹中创建新文件
添加前置元数据：

---
title: 我的新文章
date: 2025-10-30
description: 文章描述
tags:
  - 标签1
  - 标签2
draft: false
---

编写内容
使用 [[Wikilinks]] 链接到其他文章

页面

在 pages/ 文件夹中创建新文件
添加必要的前置元数据
页面将自动添加到网站

项目

在 projects/ 文件夹中创建新文件或文件夹
添加项目详情和图片
设置 featured: true 以在主页显示

快捷键

笔记库包含针对博客优化的自定义快捷键：

Ctrl/Cmd + N：新建文章
Ctrl/Cmd + Shift + N：新建页面
Ctrl/Cmd + P：命令面板
Ctrl/Cmd + O：快速切换

工作流程

典型的写作流程

创建：使用模板创建新文章
编写：在 Obsidian 中编写和编辑
预览：使用 pnpm dev 在浏览器中预览
发布：提交到 Git 并推送到仓库
部署：自动部署到您的托管平台

使用 Wikilinks

Wikilinks 是 Obsidian 的核心功能：

<!-- 链接到另一篇文章 -->
查看 [[getting-started]] 了解更多信息。

<!-- 带自定义文本的链接 -->
阅读 [[getting-started|入门指南]] 开始使用。

<!-- 链接到特定标题 -->
参考 [[formatting-reference#代码块]]。

使用标注

标注为内容添加视觉吸引力：

> [!note] 提示
> 这是一个提示标注。

> [!tip] 技巧
> 分享有用的建议。

> [!warning] 警告
> 警告潜在问题。

> [!danger] 危险
> 突出重要警告。

图片管理

添加图片

将图片放在相应文件夹的 attachments/ 子文件夹中
在 Markdown 中引用：

![图片描述](attachments/image.jpg)

<!-- 或使用 Wikilink 语法 -->
![[attachments/image.jpg]]

文章封面图片

在前置元数据中设置：

---
image: "[[attachments/cover.jpg]]"
imageAlt: "封面图片描述"
---

最佳实践

1. 使用有意义的文件名

✅ getting-started.md
✅ obsidian-guide.md
❌ post1.md
❌ untitled.md

2. 始终添加前置元数据

确保每篇文章都有：

title：文章标题
date：发布日期
description：简短描述
tags：相关标签

3. 使用草稿状态

在撰写过程中设置 draft: true：

---
draft: true
---

4. 组织文件

将相关文件放在文件夹中
使用有意义的文件夹名称
将资源放在 attachments/ 中

5. 定期备份

虽然文件在 Git 中，但定期备份笔记库是个好习惯。

故障排除

插件未加载

如果插件未加载：

打开设置 → 社区插件
确保启用社区插件
刷新已安装的插件列表

链接不工作

确保：

使用正确的文件名（不带扩展名）
目标文件存在
路径正确

图片未显示

检查：

图片路径是否正确
图片文件是否存在
使用正确的语法

总结

使用 Obsidian 与 Astro Modular 配合，您可以享受强大的写作体验和灵活的内容管理。遵循本指南，您将能够高效地创建和管理博客内容。