KnowStruct

KnowStruct is a local-first Obsidian plugin for organizing simple cards, native Canvas boards, and OCR documents in flexible project folders.

Highlights

• Browse each project like a file manager, with folder navigation, breadcrumbs, drag-and-drop, rename, move, and trash actions.
• Create a folder, standalone .sccard card, or native .canvas board at every level.
• Edit card titles and Markdown bodies directly, choose preset or custom colors, and keep linked Canvas instances synchronized.
• Import cards into native Canvas nodes that remain connectable and support collapse/expand operations.
• Convert PDFs and images to Markdown through MinerU precision parsing, MinerU Agent, or a local compatible endpoint.
• Keep all project content as ordinary files in the vault. Removing a project record does not delete its project folder.

Installation

Install KnowStruct from Settings → Community plugins, or download main.js, manifest.json, and styles.css from the matching GitHub release and place them in:

<your-vault>/.obsidian/plugins/knowstruct/

Network and privacy

• KnowStruct contains no telemetry, analytics, or advertising.
• Cards, projects, Canvas management, and local editing work without network access.
• A PDF or image is sent only when you explicitly run OCR, and only to the MinerU or compatible endpoint configured in the plugin settings.
• MinerU tokens and plugin settings remain in Obsidian's local plugin data and are not included in this repository.

Development

npm ci
npm run check

GitHub release tags must exactly match the version in manifest.json. Release assets are main.js, manifest.json, and styles.css.

---

中文说明

KnowStruct 是一个以知识项目为顶层的 Obsidian 卡片、Canvas 与 OCR 资料管理插件。

管理结构

知识项目
└─ 项目目录
   ├─ 新建：文件夹 / 卡片 / 白板
   ├─ 文件夹
   │  └─ 新建：文件夹 / 卡片 / 白板
   └─ 任意层级内容

每个项目对应仓库中的真实文件夹，默认位于 KnowStruct/Projects/<项目名称>。项目主页采用类似系统文件管理器的当前层网格：点击文件夹进入下一级，通过面包屑或返回按钮导航；首个网格始终是“新建”，可创建文件夹、卡片或白板。层级与分类完全由用户决定。

主要功能

卡片

• 标题、分割线、Markdown 正文的极简卡片。
• 8 个预设色和十六进制自定义颜色。
• 双击标题或正文编辑。
• 支持 Markdown、公式、列表、链接、图片与代码。
• 独立 .sccard 文件，不依赖 Markdown 容器。

Canvas

• 使用原生 JSON Canvas 文本节点，可继续连接边和参与 Canvas 布局。
• 移除卡片节点外层视觉框，但保留原生连接能力。
• 独立卡片与所有 Canvas 实例双向同步。
• 全部折叠 / 展开一次点击生效，并保留每个节点的展开高度。

知识项目

• 创建项目时生成独立的真实项目目录。
• 在项目根目录或任意子文件夹新建文件夹、独立卡片和原生 Canvas 白板。
• 当前层采用网格文件管理，支持文件夹逐级进入、面包屑返回、重命名、目标文件夹移动、拖放移动和移入系统回收站。
• 自动统计项目中的文件夹、卡片、白板和关联 OCR 资料。
• 删除项目仅移除管理记录，项目根目录及其中全部文件保持不变。

卡片包功能已移除。全局“卡片”页只提供卡片搜索、筛选、全选、全不选、导入 Canvas 和删除；项目内的分类统一由普通文件夹承担。

OCR / MinerU

支持把仓库中的 PDF、PNG、JPG、WebP、BMP 和 TIFF 转换为 Markdown：

• MinerU 精准解析：https://mineru.net/api/v4/file-urls/batch
  • Token 鉴权。
  • 签名 URL 上传、异步轮询、下载并解压结果包。
  • 保存 Markdown 及结果包中的图片资源。
• MinerU Agent 轻量解析：https://mineru.net/api/v1/agent/parse/file
  • 无 Token，采用签名上传与异步轮询。
  • 默认开启 OCR、表格和公式识别。
• 本地或自定义接口：默认预设 http://127.0.0.1:8000/file_parse
  • multipart 文件上传。
  • 支持自定义文件字段、Bearer Token 和附加 JSON 参数。

官方接口说明：MinerU 文档解析 API。

转换结果默认保存到：

KnowStruct/OCR/<项目名称>/<资料名称>.md

输出 Markdown 会记录：

knowstruct: ocr
ks-project-id: <永久项目 ID>
ks-project-name: <项目名称>
ks-ocr-source: <来源文件路径>
ks-ocr-created-at: <转换时间>
ks-ocr-engine: <解析引擎>

可通过以下入口执行：

• 命令面板：KnowStruct：使用 MinerU OCR 转换 PDF 或图片
• PDF 或图片的文件右键菜单：KnowStruct：使用 MinerU OCR
• 管理右侧栏的“项目 → OCR 资料”
• 全局“OCR”页

侧栏

KnowStruct 默认在右侧栏打开。宽度完全使用 Obsidian 原生侧栏行为，可拖拽调整并由工作区记忆，没有固定最大宽度。

设置

• 默认卡片颜色、圆角、阴影和调色按钮。
• 独立卡片根目录。
• 新建项目的根目录。
• MinerU 接口预设与自定义地址。
• MinerU Token、multipart 文件字段和附加 JSON 参数。
• OCR 输出目录。

本地构建

npm install
npm run check

npm run check 会执行单元测试、TypeScript 类型检查和生产构建。

安装

将下列三个文件放入仓库的 .obsidian/plugins/knowstruct/：

main.js
manifest.json
styles.css

然后在 Obsidian 的“第三方插件”中启用 KnowStruct。