odox/notes/implementation.md

## 核心功能

1. **Markdown 文件导出**：将 `.md` 文件导出到 VitePress 的 docs 目录，自动处理资源文件
2. **Canvas 文件导出**：将 `.canvas` 文件渲染为图片并生成对应的 `.canvas.md` 文件
3. **资源文件管理**：自动复制和处理图片、Canvas 等资源文件
4. **路径规则配置**：支持多种目录结构和命名规则

## 主要流程

### 整体架构流程

```mermaid
graph TB
    Start[用户触发导出] --> CheckType{检查文件类型}
    CheckType -->|Canvas 文件| CanvasFlow[Canvas 导出流程]
    CheckType -->|Markdown 文件| MarkdownFlow[Markdown 导出流程]

    CanvasFlow --> RenderCanvas[渲染 Canvas 为图片]
    RenderCanvas --> SaveImage[保存图片到 assetsPath]
    SaveImage --> GenerateCanvasMD[生成 .canvas.md 文件]
    GenerateCanvasMD --> WriteCanvas[写入文件]
    WriteCanvas --> End[完成]

    MarkdownFlow --> ReadContent[读取文件内容]
    ReadContent --> ProcessAssets[扫描并处理资源]
    ProcessAssets --> CollectLinks[收集链接和嵌入]
    CollectLinks --> Separate{分类资源}

    Separate -->|Canvas 文件| RenderCanvas
    Separate -->|普通资源| CopyAssets[复制资源到 assetsPath]

    CopyAssets --> UpdateLinks[更新内容中的链接]
    RenderCanvas --> UpdateCanvasLinks[更新 Canvas 链接为 Viewer 组件]

    UpdateCanvasLinks --> CalculatePath[计算输出路径]
    UpdateLinks --> CalculatePath

    CalculatePath --> ApplyRules{应用路径规则}
    ApplyRules --> PreserveFolder[preserveFolderStructure?]
    PreserveFolder -->|是| KeepStructure[保留文件夹结构]
    PreserveFolder -->|否| Flatten[扁平化]

    KeepStructure --> NestNote{nestNoteFolder?}
    Flatten --> NestNote

    NestNote -->|是| CreateIndex[创建 index.md]
    NestNote -->|否| UseFilename[使用原文件名]

    CreateIndex --> WriteMD[写入 Markdown 文件]
    UseFilename --> WriteMD

    WriteMD --> End
```

### 资源处理流程

```mermaid
graph TB
    Start[processAssets 开始] --> GetCache[获取文件缓存]
    GetCache --> CheckCache{缓存存在?}
    CheckCache -->|否| ReturnContent[返回原内容]
    CheckCache -->|是| CollectStart[收集资源]

    CollectStart --> ScanEmbeds[扫描 embeds]
    ScanEmbeds --> CheckEmbed{是 Canvas?}
    CheckEmbed -->|是| AddCanvas[添加到 canvasFiles]
    CheckEmbed -->|否| AddAsset[添加到 assetsToCopy]

    AddCanvas --> ScanLinks[扫描 links]
    AddAsset --> ScanLinks

    ScanLinks --> CheckLink{是本地资源?}
    CheckLink -->|是| AddAsset
    CheckLink -->|否| ProcessCanvas

    ProcessCanvas[处理 Canvas 文件] --> RenderEach[遍历每个 Canvas]
    RenderEach --> CallRender[调用 renderCanvas]
    CallRender --> SavePNG[保存为 PNG]
    SavePNG --> UpdateCanvasLink[更新为 Viewer 组件]

    UpdateCanvasLink --> CopyAssets[复制普通资源]
    CopyAssets --> CopyEach[遍历每个资源]
    CopyEach --> ReadBinary[Binary 模式读取]
    ReadBinary --> WriteAsset[写入 assetsPath]
    WriteAsset --> UpdateAssetLink[更新资源链接]

    UpdateAssetLink --> ReturnContent[返回更新后的内容]
```

### Canvas 渲染流程

```mermaid
graph TB
    Start[renderCanvas 开始] --> OpenFile[打开 Canvas 文件]
    OpenFile --> GetCanvas[获取 Canvas 对象]
    GetCanvas --> CheckCanvas{Canvas 存在?}
    CheckCanvas -->|否| ReturnNull[返回 null]
    CheckCanvas -->|是| CalcSystem[计算系统参数]

    CalcSystem --> GetZoom[获取缩放级别]
    GetZoom --> CalcPixel[计算设备像素比]
    CalcPixel --> CalcScale[计算缩放校正系数]

    CalcScale --> GetNodes[获取所有节点]
    GetNodes --> CalcBBox[计算边界框]
    CalcBBox --> CalcSize[计算宽度和高度]

    CalcSize --> CalcLimit{计算缩放限制}
    CalcLimit --> CheckLimit{超过 16284px?}
    CheckLimit -->|是| UseLimit[使用限制值]
    CheckLimit -->|否| UseZoom[使用原始缩放]

    UseLimit --> PrepareCanvas[准备 Canvas 环境]
    UseZoom --> PrepareCanvas

    PrepareCanvas --> DeselectAll[取消选择]
    DeselectAll --> AddScreenshotting[添加截图样式]
    AddScreenshotting --> AppendToBody[附加到 body]

    AppendToBody --> SetPosition[设置位置]
    SetPosition --> CalcViewport[计算视口]
    CalcViewport --> SetCanvasZoom[设置 Canvas 缩放]
    SetCanvasZoom --> RequestFrame[请求帧]

    RequestFrame --> WaitRender[等待渲染完成]
    WaitRender --> CalcTiles[计算分块数量]
    CalcTiles --> CreateFinalCanvas[创建最终 Canvas]

    CreateFinalCanvas --> RenderLoop[渲染循环]
    RenderLoop --> SetViewport[设置视口位置]
    SetViewport --> RequestTileFrame[请求分块帧]
    RequestTileFrame --> WaitTile[等待渲染]
    WaitTile --> CapturePage[捕获页面]
    CapturePage --> ConvertToPNG[转换为 PNG]
    ConvertToPNG --> DrawToFinal[绘制到最终 Canvas]
    DrawToFinal --> CheckNext{还有分块?}
    CheckNext -->|是| SetViewport
    CheckNext -->|否| ConvertFinal[转换最终 Canvas]

    ConvertFinal --> ToBlob[转换为 Blob]
    ToBlob --> ToArrayBuffer[转换为 ArrayBuffer]
    ToArrayBuffer -> ToUint8Array[转换为 Uint8Array]
    ToUint8Array --> ReturnResult[返回结果]

    ReturnResult --> Cleanup[清理环境]
    Cleanup --> RestoreStyles[恢复样式]
    RestoreStyles --> ResetCanvas[重置 Canvas]
    ResetCanvas --> End[结束]

    ReturnNull --> End
```

## 核心方法说明

### 1. exportCurrentNote()
**位置**：main.ts:75-89

**功能**：导出当前活动的文件
- 获取活动文件
- 验证文件类型（md 或 canvas）
- 调用 exportNote()

### 2. exportNote()
**位置**：main.ts:92-135

**功能**：导出单个文件的主入口
- 判断文件类型并分发到不同的处理逻辑
- Markdown 文件：读取内容 → 处理资源 → 计算路径 → 写入文件
- Canvas 文件：调用 exportCanvasFile()

### 3. exportCanvasFile()
**位置**：main.ts:138-192

**功能**：专门处理 Canvas 文件导出
1. 渲染 Canvas 为 PNG 图片
2. 保存图片到 assetsPath（扁平化）
3. 计算 .canvas.md 文件路径
4. 生成包含 `<Viewer>` 组件的 Markdown 内容
5. 写入文件

**路径规则示例**：
```typescript
// 保留文件夹 + 嵌套
notes/测试用.canvas → docs/notes/测试用.canvas/index.md

// 仅嵌套
notes/测试用.canvas → docs/测试用.canvas/index.md

// 保留文件夹
notes/测试用.canvas → docs/notes/测试用.canvas.md

// 默认
notes/测试用.canvas → docs/测试用.canvas.md
```

### 4. processAssets()
**位置**：main.ts:195-308

**功能**：扫描并处理 Markdown 文件中的资源

**处理流程**：
1. 使用 metadataCache 获取文件的 embeds 和 links
2. 分类资源：Canvas 文件 vs 普通资源
3. 处理 Canvas：渲染为图片并更新链接为 `<Viewer>` 组件
4. 复制普通资源到 assetsPath
5. 更新内容中的所有资源链接

**链接格式支持**：
- Markdown 格式：`![](path)`
- Wikilink 格式：`![[path]]`

### 5. renderCanvas()
**位置**：main.ts:368-556

**功能**：使用 Obsidian 内部 API 将 Canvas 渲染为 PNG 图片

**技术要点**：
- 使用 Electron 的 `webContents.capturePage()` API
- 分块渲染：处理大型 Canvas（避免超过 16284px 限制）
- 缩放校正：考虑系统缩放和设备像素比
- 像素级精确：使用 binary 模式保留原始格式

**分块渲染算法**：
```typescript
// 计算分块数量
const cols = Math.ceil((bbox.maxX - bbox.minX) / tileWidth);
const rows = Math.ceil((bbox.maxY - bbox.minY) / tileHeight);

// 逐个渲染分块并拼接
for (let row = 0; row < rows; row++) {
    for (let col = 0; col < cols; col++) {
        // 设置视口位置
        canvas.x = canvas.tx = startX + col * tileWidth;
        canvas.y = canvas.ty = startY + row * tileHeight;

        // 捕获并绘制
        const capturedData = await webContents.capturePage(...);
        ctx.drawImage(img, col * O * s, row * F * s);
    }
}
```

### 6. updateLinksInContent()
**位置**：main.ts:311-364

**功能**：更新内容中的资源链接

**智能匹配**：
尝试多种可能的路径格式：
- 完整路径：`notes/image.png`
- 相对路径：`image.png`
- URL 编码：`notes%2Fimage.png`
- 文件名：`image.png`

**统一输出**：
所有资源链接转换为根路径：`/filename.png`

### 7. updateCanvasLinksInContent()
**位置**：main.ts:593-648

**功能**：将 Canvas 链接转换为 `<Viewer>` 组件

**转换规则**：
```markdown
![](测试用.canvas)  →  <Viewer src="/测试用.canvas.png" />
![[测试用.canvas]]  →  <Viewer src="/测试用.canvas.png" />
```

## 配置选项

### settings.ts

```typescript
interface vitepressExporterSettings {
    docsPath: string;              // VitePress docs 目录路径，默认 'docs'
    assetsPath: string;            // 资源目录路径，默认 'docs/public'
    nestNoteFolder: boolean;       // 是否为每个笔记创建文件夹，默认 true
    preserveFolderStructure: boolean; // 是否保留原始文件夹结构，默认 true
}
```

### 路径规则矩阵

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

## 技术实现要点

### 1. Binary 模式文件操作

使用 binary 模式保留文件原始格式：
```typescript
// 读取
const contentBuffer = await vault.readBinary(file);
const content = new TextDecoder().decode(contentBuffer);

// 写入
const buffer = new TextEncoder().encode(content);
await vault.adapter.writeBinary(path, buffer.buffer);
```

### 2. Obsidian 元数据缓存

使用 `metadataCache` 解析链接：
```typescript
const cache = metadataCache.getCache(sourceFile.path);
const resolvedLink = metadataCache.getFirstLinkpathDest(link, sourceFile.path);
```

### 3. Electron API 集成

使用 Obsidian 内部的 Electron API：
```typescript
const electron = window.electron?.remote;
const webContents = electron?.getCurrentWebContents();
const capturedData = await webContents.capturePage({ x, y, width, height });
```

### 4. 链接解析兼容性

支持多种链接格式：
- 绝对路径和相对路径
- URL 编码和未编码
- Markdown 标准格式和 Obsidian Wikilink

### 5. Canvas 渲染优化

- **分块渲染**：避免单个 Canvas 过大
- **异步处理**：使用 `requestAnimationFrame` 确保渲染完成
- **缩放校正**：考虑系统 DPI 设置
- **内存管理**：及时释放临时对象（URL.revokeObjectURL）

## 文件结构

```
.obsidian/plugins/vitepress-exporter/
├── src/
│   ├── main.ts          # 主插件逻辑（650 行）
│   └── settings.ts      # 设置定义和 UI
├── notes/               # 文档和说明
├── manifest.json        # 插件清单
└── package.json         # 依赖管理
```

## 依赖项

- **Obsidian API**：插件框架
- **Electron**：Canvas 渲染（桌面版）
- **TypeScript**：类型安全

## 使用场景

1. **从 Obsidian 迁移到 VitePress**：将个人知识库转换为静态网站
2. **技术文档发布**：在 Obsidian 中编写，发布到 VitePress
3. **Canvas 可视化**：将 Obsidian Canvas 导出为交互式图片
4. **自动化工作流**：结合 CI/CD 实现自动部署

## 局限性

1. **平台依赖**：Canvas 渲染仅支持桌面版 Obsidian（需要 Electron）
2. **VitePress 特定**：生成的 `<Viewer>` 组件需要在 VitePress 中配置
3. **链接转换**：复杂的链接语法可能需要手动调整
4. **大型 Canvas**：分块渲染可能耗时较长

## 未来改进方向

1. **增量导出**：只导出修改过的文件
2. **批量导出**：支持一次性导出整个文件夹
3. **配置预设**：保存常用的导出配置
4. **错误恢复**：更完善的错误处理和回滚机制
5. **性能优化**：并行处理多个文件