icrdr/odox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Rename plugin to Odox and enhance documentation for static site export features

Browse Source
This commit is contained in:
马南
2026-04-22 11:08:20 +08:00
parent f0ca3776f0
commit 0e051b7293
7 changed files with 298 additions and 171 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
notes/implementation.md
View File

@@ -1,9 +1,10 @@
## 核心功能
1. **Markdown 文件导出**：将 `.md` 文件导出到 VitePress 的 docs 目录，自动处理资源文件
2. **Canvas 文件导出**：将 `.canvas` 文件渲染为图片并生成对应的 `.canvas.md` 文件
3. **资源文件管理**：自动复制和处理图片、Canvas 等资源文件
4. **路径规则配置**：支持多种目录结构和命名规则
1. **Markdown 文件导出**：将 `.md` 文件导出到静态文档站点目录，自动处理资源文件
2. **Canvas 文件导出**：将 `.canvas` 文件渲染为高清 PNG 图片并生成对应的 `.canvas.md` 文件
3. **资源文件管理**：自动复制和处理图片、Canvas 等资源文件到统一目录
4. **路径规则配置**：支持多种目录结构和命名规则，灵活配置输出路径
5. **透明背景支持**：Canvas 导出时可选择透明背景，移除 Obsidian 的点状背景图案
## 主要流程
@@ -115,7 +116,11 @@ graph TB
PrepareCanvas --> DeselectAll[取消选择]
DeselectAll --> AddScreenshotting[添加截图样式]
AddScreenshotting --> AppendToBody[附加到 body]
AddScreenshotting --> CheckTransparent{透明背景?}
CheckTransparent -->|是| AddTransparentClass[添加透明样式类]
CheckTransparent -->|否| HideElements[隐藏页面元素]
AddTransparentClass --> HideElements
HideElements --> AppendToBody[附加到 body]
AppendToBody --> SetPosition[设置位置]
SetPosition --> CalcViewport[计算视口]
@@ -143,7 +148,11 @@ graph TB
ToUint8Array --> ReturnResult[返回结果]
ReturnResult --> Cleanup[清理环境]
Cleanup --> RestoreStyles[恢复样式]
Cleanup --> CheckTransparentCleanup{透明背景?}
CheckTransparentCleanup -->|是| RestoreHiddenElements[恢复隐藏元素]
CheckTransparentCleanup -->|否| RestoreStyles[恢复样式]
RestoreHiddenElements --> RemoveBodyClasses[移除 body 类]
RemoveBodyClasses --> RestoreStyles
RestoreStyles --> ResetCanvas[重置 Canvas]
ResetCanvas --> End[结束]
@@ -172,10 +181,10 @@ graph TB
**位置**：main.ts:138-192
**功能**：专门处理 Canvas 文件导出
1. 渲染 Canvas 为 PNG 图片
2. 保存图片到 assetsPath（扁平化）
1. 渲染 Canvas 为 PNG 图片（支持透明背景）
2. 保存图片到 assetsPath（扁平化存储）
3. 计算 .canvas.md 文件路径
4. 生成包含 `<Viewer>` 组件的 Markdown 内容
4. 使用配置的嵌入模板生成 Markdown 内容
5. 写入文件
**路径规则示例**：
@@ -219,6 +228,8 @@ notes/测试用.canvas → docs/测试用.canvas.md
- 分块渲染：处理大型 Canvas（避免超过 16284px 限制）
- 缩放校正：考虑系统缩放和设备像素比
- 像素级精确：使用 binary 模式保留原始格式
- 透明背景：通过临时 CSS 类和 DOM 操作实现透明背景导出
- 智能隐藏：导出时临时隐藏页面其他元素，确保只捕获 Canvas 内容
**分块渲染算法**：
```typescript
@@ -262,6 +273,11 @@ for (let row = 0; row < rows; row++) {
**转换规则**：
```markdown
// 默认模板：![]({url})
![](测试用.canvas) → ![](/测试用.canvas.png)
![[测试用.canvas]] → ![](/测试用.canvas.png)
// 自定义模板：<Viewer src="{url}" />
![](测试用.canvas) → <Viewer src="/测试用.canvas.png" />
![[测试用.canvas]] → <Viewer src="/测试用.canvas.png" />
```
@@ -271,22 +287,24 @@ for (let row = 0; row < rows; row++) {
### settings.ts
```typescript
interface vitepressExporterSettings {
docsPath: string; // VitePress docs 目录路径，默认 'docs'
assetsPath: string; // 资源目录路径，默认 'docs/public'
nestNoteFolder: boolean; // 是否为每个笔记创建文件夹，默认 true
preserveFolderStructure: boolean; // 是否保留原始文件夹结构，默认 true
interface odoxSettings {
docsPath: string; // 文档站点目录路径，默认 'docs'
assetsPath: string; // 资源目录路径，默认 'docs/public'
nestNoteFolder: boolean; // 是否为每个笔记创建文件夹，默认 true
preserveFolderStructure: boolean; // 是否保留原始文件夹结构，默认 true
transparentCanvas: boolean; // 是否使用透明背景导出 Canvas，默认 true
canvasEmbedTemplate: string; // Canvas 嵌入模板，默认 '![]({url})'
}
```
### 路径规则矩阵
| preserveFolderStructure | nestNoteFolder | 输入 | 输出 |
|---------|---------|------|------|
| true | true | notes/test.md | docs/notes/test/index.md |
| true | false | notes/test.md | docs/notes/test.md |
| false | true | notes/test.md | docs/test/index.md |
| false | false | notes/test.md | docs/test.md |
| preserveFolderStructure | nestNoteFolder | Markdown 输入 | Markdown 输出 | Canvas 输入 | Canvas 输出 |
|---------|---------|------|------|------|------|
| true | true | notes/test.md | docs/notes/test/index.md | notes/test.canvas | docs/notes/test.canvas/index.md |
| true | false | notes/test.md | docs/notes/test.md | notes/test.canvas | docs/notes/test.md |
| false | true | notes/test.md | docs/test/index.md | notes/test.canvas | docs/test.canvas/index.md |
| false | false | notes/test.md | docs/test.md | notes/test.canvas | docs/test.canvas.md |
## 技术实现要点
@@ -329,21 +347,25 @@ const capturedData = await webContents.capturePage({ x, y, width, height });
### 5. Canvas 渲染优化
- **分块渲染**：避免单个 Canvas 过大
- **分块渲染**：避免单个 Canvas 过大，超过 16284px 限制
- **异步处理**：使用 `requestAnimationFrame` 确保渲染完成
- **缩放校正**：考虑系统 DPI 设置
- **缩放校正**：考虑系统 DPI 设置，确保高清输出
- **内存管理**：及时释放临时对象（URL.revokeObjectURL）
- **透明背景**：通过 CSS 类和 DOM 操作实现透明背景导出
- **智能隐藏**：导出时临时隐藏页面其他元素，确保只捕获 Canvas 内容
## 文件结构
```
.obsidian/plugins/vitepress-exporter/
.obsidian/plugins/odox/
├── src/
│ ├── main.ts # 主插件逻辑（650 行）
│ ├── main.ts # 主插件逻辑（约 680 行）
│ └── settings.ts # 设置定义和 UI
├── notes/ # 文档和说明
│ └── implementation.md # 实现细节文档
├── manifest.json # 插件清单
└── package.json # 依赖管理
├── package.json # 依赖管理
└── main.js # 编译后的插件文件
```
## 依赖项
@@ -354,22 +376,25 @@ const capturedData = await webContents.capturePage({ x, y, width, height });
## 使用场景
1. **从 Obsidian 迁移到 VitePress**：将个人知识库转换为静态网站
2. **技术文档发布**：在 Obsidian 中编写，发布到 VitePress
3. **Canvas 可视化**：将 Obsidian Canvas 导出为交互式图片
4. **自动化工作流**：结合 CI/CD 实现自动部署
1. **从 Obsidian 迁移到静态站点**：将个人知识库转换为 VitePress、Docusaurus 等静态网站
2. **技术文档发布**：在 Obsidian 中编写，发布到文档站点
3. **Canvas 可视化**：将 Obsidian Canvas 导出为高清 PNG 图片
4. **自动化工作流**：结合 CI/CD 实现自动部署文档站点
## 局限性
## 技术优势
1. **平台依赖**：Canvas 渲染仅支持桌面版 Obsidian（需要 Electron）
2. **VitePress 特定**：生成的 `<Viewer>` 组件需要在 VitePress 中配置
3. **链接转换**：复杂的链接语法可能需要手动调整
4. **大型 Canvas**：分块渲染可能耗时较长
1. **高质量渲染**：使用 Obsidian 原生渲染引擎，确保导出内容与编辑器中一致
2. **智能资源管理**：自动识别、复制和更新资源文件引用
3. **灵活配置**：支持多种目录结构和命名规则，适应不同的项目需求
4. **透明背景支持**：Canvas 导出时可移除背景图案，适合嵌入各种主题的网站
5. **分块渲染技术**：处理大型 Canvas 文件，避免尺寸限制
## 未来改进方向
1. **增量导出**：只导出修改过的文件
2. **批量导出**：支持一次性导出整个文件夹
3. **配置预设**：保存常用的导出配置
4. **错误恢复**：更完善的错误处理和回滚机制
5. **性能优化**：并行处理多个文件
1. **增量导出**：只导出修改过的文件，提高大项目的导出效率
2. **批量导出**：支持一次性导出整个文件夹或整个项目
3. **配置预设**：保存常用的导出配置，快速切换不同项目的导出规则
4. **错误恢复**：更完善的错误处理和回滚机制，导出失败时恢复原状态
5. **性能优化**：并行处理多个文件，利用多核 CPU 加速导出过程
6. **进度显示**：为批量导出操作提供进度条和详细的状态信息
7. **导出历史**：记录导出历史，支持撤销和回滚操作