112 lines
3.5 KiB
Markdown
112 lines
3.5 KiB
Markdown
# Odox - Obsidian Plugin
|
||
|
||
## 功能
|
||
|
||
这个 Obsidian 插件用于自动化发布 Obsidian 笔记到静态文档网站（如 VitePress、Docusaurus 等）：
|
||
|
||
- ✅ 将当前 markdown 文件导出到 `docs/` 目录
|
||
- ✅ 自动复制引用的资源文件到 `docs/public/` 目录
|
||
- ✅ 更新 markdown 中的资源路径为根路径引用
|
||
- ✅ Canvas 文件渲染为高清 PNG 图片
|
||
- ✅ 支持 Canvas 透明背景导出
|
||
- ✅ 灵活的目录结构和命名规则配置
|
||
|
||
## 安装
|
||
|
||
插件已经安装在这个项目的 `.obsidian/plugins/odox/` 目录下。
|
||
|
||
1. 在 Obsidian 中打开这个项目
|
||
2. 进入设置 → 第三方插件
|
||
3. 启用 "Odox" 插件
|
||
|
||
## 使用
|
||
|
||
### 方式 1：命令面板
|
||
1. 打开一个 markdown 或 canvas 文件
|
||
2. 按 `Ctrl+P` (或 `Cmd+P`) 打开命令面板
|
||
3. 输入 "Export to docs"
|
||
4. 选择 "Export current note to docs"
|
||
|
||
### 方式 2：文件菜单
|
||
- 在文件管理器中右键点击文件
|
||
- 选择 "Export to docs" 选项
|
||
|
||
### 方式 3：编辑器菜单
|
||
- 在编辑器中右键点击
|
||
- 选择 "Export to docs" 选项
|
||
|
||
### 方式 4：快捷键
|
||
- 可以在 Obsidian 的快捷键设置中为导出命令设置快捷键
|
||
|
||
## 配置
|
||
|
||
在插件设置中可以配置：
|
||
|
||
- **Wiki path**: 导出的 markdown 文件存放目录（默认：`docs`）
|
||
- **Assets path**: 资源文件存放目录（默认：`docs/public`）
|
||
- **Nest note folder**: 是否为每个笔记创建文件夹（默认：开启）
|
||
- **Preserve folder structure**: 是否保留原始文件夹结构（默认：开启）
|
||
- **Transparent canvas background**: 导出 Canvas 时使用透明背景（默认：开启）
|
||
- **Canvas embed template**: Canvas 嵌入模板，使用 `{url}` 作为图片路径占位符
|
||
|
||
## 工作流程
|
||
|
||
1. 用户在 Obsidian 中编写笔记
|
||
2. 笔记中引用的资源（图片、Canvas 等）可以放在任意位置
|
||
3. 触发导出命令
|
||
4. 插件自动：
|
||
- 将 markdown 文件复制到 `docs/` 目录
|
||
- 扫描并复制所有引用的资源到 `docs/public/` 目录
|
||
- 将 Canvas 文件渲染为高清 PNG 图片
|
||
- 更新 markdown 中的资源路径为根路径引用（如 `/image.png`）
|
||
|
||
## Canvas 导出
|
||
|
||
Canvas 文件会通过以下方式处理：
|
||
|
||
1. 使用 Obsidian 内部 API 渲染 Canvas 为 PNG 图片
|
||
2. 保存图片到 `docs/public/` 目录
|
||
3. 生成对应的 `.canvas.md` 文件，使用配置的嵌入模板
|
||
4. 支持透明背景导出（移除 Obsidian 的点状背景）
|
||
|
||
## 当前状态
|
||
|
||
- ✅ 基础插件框架
|
||
- ✅ Markdown 文件导出功能
|
||
- ✅ 资源文件自动复制和路径更新
|
||
- ✅ Canvas 文件渲染为 PNG 图片
|
||
- ✅ Canvas 透明背景支持
|
||
- ✅ 分块渲染大型 Canvas（避免尺寸限制）
|
||
- ✅ 灵活的路径规则配置
|
||
|
||
## 技术特点
|
||
|
||
- **Binary 模式文件操作**：保留原始文件格式（包括行尾空格）
|
||
- **智能链接解析**：支持多种链接格式（Markdown、Wikilink、相对路径、绝对路径）
|
||
- **分块渲染**：对大型 Canvas 进行分块渲染，避免超过 16284px 的尺寸限制
|
||
- **缩放校正**：考虑系统 DPI 和缩放设置，确保高清输出
|
||
- **Electron 集成**：使用 Obsidian 内部的 Electron API 实现 Canvas 截图
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
cd .obsidian/plugins/odox
|
||
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 开发模式（自动重新编译）
|
||
npm run dev
|
||
|
||
# 生产构建
|
||
npm run build
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
- 确保项目中有配置的目标目录
|
||
- 资源文件会被复制，不会移动原文件
|
||
- 如果目标文件已存在，会被覆盖
|
||
- Canvas 渲染仅支持桌面版 Obsidian（需要 Electron）
|
||
- 生成的 `<Viewer>` 组件需要在静态站点中配置对应组件
|