# Obsidian Halo 插件使用指南

> 完整的 Halo 博客同步插件使用手册

## 📦 安装和配置

### 1. 安装插件

1. 在 Obsidian 设置中进入「社区插件」
2. 搜索「Halo」或「obsidian-halo」
3. 安装并启用插件

### 2. 配置站点

1. 进入插件设置（设置 → 插件选项 → Halo）
2. 点击「添加站点」
3. 填写以下信息：
   - **站点名称**：给你的站点起个名字
   - **站点地址**：你的 Halo 博客地址，如 `https://blog.example.com`
   - **个人令牌**：在 Halo 后台 → 个人资料 → 个人令牌 中创建

4. 点击「验证」确保配置正确
5. 可以设置一个「默认站点」

---

## 🎛️ 图标说明

插件在左侧 ribbon 栏添加了两个图标：

| 图标 | 位置 | 功能 |
|------|------|------|
| 🔵 Halo Logo | Ribbon 栏 | 快速发布当前文档到 Halo |
| 🔄 同步图标 | Ribbon 栏 | 打开同步状态面板 |

---

## 📋 所有命令列表

在 Obsidian 中按 `Ctrl+P`（或 `Cmd+P`）打开命令面板，输入「Halo」查找所有命令：

### 发布和同步

| 命令 | 说明 | 使用场景 |
|------|------|----------|
| `Halo: 发布到 Halo` | 发布当前文档到 Halo | 编辑完文章后发布 |
| `Halo: 发布到 Halo（使用默认配置）` | 使用默认站点发布 | 快速发布，不选择站点 |
| `Halo: 从 Halo 更新内容` | 从 Halo 同步内容到本地 | Halo 端有更新时同步 |
| `Halo: 从 Halo 拉取文档` | 打开文章列表选择拉取 | 想要从 Halo 拉取已存在的文章 |

### 文章管理

| 命令 | 说明 | 使用场景 |
|------|------|----------|
| `Halo: 从 Markdown 文件导入` | 从 Vault 中选择文件导入 Halo | 导入已存在的文件 |
| `Halo: 删除 Halo 文章` | 删除已发布的文章（需在编辑器中执行）| 删除文章时使用 |
| `Halo: 搜索 Halo 文章` | 搜索 Halo 上的文章 | 快速查找文章 |
| `Halo: 打开同步状态面板` | 打开同步状态面板 | 查看所有已发布文章的状态 |

### 导出功能

| 命令 | 说明 | 使用场景 |
|------|------|----------|
| `Halo: 导出为 Markdown` | 导出当前文章为 .md 文件 | 备份或迁移内容 |
| `Halo: 导出为 JSON` | 导出当前文章为 .json 文件 | 备份元数据和内容 |

### 分类和标签管理

| 命令 | 说明 | 使用场景 |
|------|------|----------|
| `Halo: 管理标签` | 打开标签管理弹窗 | 创建、编辑、删除标签 |
| `Halo: 管理分类` | 打开分类管理弹窗 | 创建、编辑、删除分类 |

---

## 🚀 快速开始

### 首次发布文章

1. 在 Obsidian 中创建或打开一个 Markdown 文件
2. 添加 frontmatter 元数据（可选）：

   ```yaml
   ---
   title: 我的第一篇文章
   slug: my-first-post
   tags:
     - 教程
     - Obsidian
   categories:
     - 笔记方法
   ---
   
   文章内容...
   ```

3. 点击左侧的 **Halo Logo** 图标，或按 `Ctrl+P` 输入「发布到 Halo」
4. 如果有多个站点，选择目标站点
5. 等待发布成功提示

### 从 Halo 拉取文章

1. 按 `Ctrl+P` 输入「从 Halo 拉取文档」
2. 选择站点
3. 在列表中找到要拉取的文章
4. 点击「拉取」按钮
5. 文章将自动创建到 Vault 中

### 查看同步状态

1. 点击左侧的 **同步图标**（或按 `Ctrl+P` 输入「同步状态」）
2. 右侧面板将显示所有已发布文章
3. 可以执行快速操作：更新、拉取

---

## 📝 Frontmatter 说明

发布文章时，可以设置以下 frontmatter：

```yaml
---
title: 文章标题（必填，用于显示标题）
slug: article-slug（可选，用于 URL）
excerpt: 文章摘要（可选）
cover: https://example.com/cover.jpg（可选，封面图）
tags:
  - 标签1
  - 标签2
categories:
  - 分类1
  - 分类2
halo:
  site: https://blog.example.com（自动填充）
  name: xxxxx（自动填充，文章ID）
  publish: true（自动填充，发布状态）
---
```

---

## 🔧 常见问题

### Q: 为什么我的图片没有上传到 Halo？

请确保在插件设置中启用了「图片上传」功能：
1. 进入插件设置
2. 找到「图片上传设置」
3. 勾选「启用图片上传」

### Q: 如何发布后立即发布而不是存为草稿？

在插件设置中勾选「默认发布文章」。

### Q: 如何管理标签和分类？

1. 按 `Ctrl+P` 输入「管理标签」或「管理分类」
2. 在弹窗中可以创建、编辑、删除标签和分类

### Q: 想要批量操作怎么办？

使用同步状态面板：
1. 点击同步图标打开面板
2. 查看所有已发布文章
3. 可以逐个更新或拉取

### Q: 导出功能在哪里？

在命令面板中搜索「导出」：
- `Halo: 导出为 Markdown` - 导出为带 frontmatter 的 .md 文件
- `Halo: 导出为 JSON` - 导出为 JSON 格式（含元数据）

### Q: 搜索功能怎么用？

1. 按 `Ctrl+P` 输入「搜索 Halo」
2. 输入关键词搜索标题或 slug
3. 可以筛选：全部 / 已发布 / 草稿

---

## ⚠️ 注意事项

1. **备份重要数据**：删除操作不可撤销，请谨慎操作
2. **图片上传**：首次上传图片需要较长时间，请耐心等待
3. **令牌权限**：确保个人令牌有文章管理权限

---

## 📞 获取帮助

如果遇到问题，请：
1. 查看控制台错误信息（开发者工具）
2. 检查 Halo 站点是否正常运行
3. 确认令牌权限是否足够

---

最后更新：2024年4月