Obsidian/obsidian-halo/docs/usage-guide.md

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 元数据（可选）：

   ---
   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：

---
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月