PaperForge banner

# PaperForge [![Version](https://img.shields.io/github/v/release/LLLin000/PaperForge?style=for-the-badge&label=version)](https://github.com/LLLin000/PaperForge/releases) [![Python](https://img.shields.io/pypi/pyversions/paperforge?style=for-the-badge&logo=python&logoColor=white&color=3775A9)](https://python.org) [![License](https://img.shields.io/badge/license-CC%20BY--NC--SA%204.0-lightgreen?style=for-the-badge)](LICENSE) [简体中文](README.zh.md) · **English** > **铸知识为器，启洞见之明。 — Forge Knowledge, Empower Insight.** PaperForge brings your Zotero library into Obsidian. Sync papers, run OCR, extract figures, and do AI-assisted deep reading — all inside a single vault. --- ## 0. What PaperForge Is PaperForge is **not just an Obsidian plugin**. It has two parts: | Part | What | Does | Where | |------|------|------|-------| | Obsidian Plugin | `main.js` + `manifest.json` + `styles.css` | Dashboard, buttons, settings UI | `.obsidian/plugins/paperforge/` in your vault | | Python Package | `paperforge` | Sync, OCR, Doctor, repair | Your system Python (`pip install`) | The plugin is the **interface**. The Python package is the **engine**. Every button you click in the plugin actually runs a Python command behind the scenes. **After installing the plugin, you MUST verify that the Python package is also installed and version-matched.** --- ## 1. Install the Obsidian Plugin ### Option A: Community Plugin Browser (Recommended) 1. Open Obsidian → `Settings` → `Community plugins` → `Browse` 2. Search for **PaperForge** 3. Click `Install`, then `Enable` > Community plugins auto-update through Obsidian. No extra steps needed. ### Option B: BRAT If you need beta versions or the plugin hasn't appeared in search yet: 1. Install **BRAT** from the Obsidian community plugin browser 2. Open BRAT settings → `Add Beta Plugin` 3. Enter: `https://github.com/LLLin000/PaperForge` 4. Enable PaperForge in Settings → Community Plugins ### Option C: Manual Download 1. Go to [Releases](https://github.com/LLLin000/PaperForge/releases) 2. Download the three files: `main.js`, `manifest.json`, `styles.css` 3. Create `.obsidian/plugins/paperforge/` in your vault 4. Put the three files there 5. Restart Obsidian → Settings → Community Plugins → enable PaperForge > Manual install does not auto-update. You'll need to re-download for each new version. --- ## 2. Install the Python Package After enabling the plugin, open the PaperForge settings tab. You'll see a **Runtime Status** section: ``` Plugin v1.5.0 → Python Package v1.5.0 ✓ Matched ``` - If it says "Not installed" → click **Open Wizard** to re-run the setup process - If it says "Mismatch" → the Python package auto-updates when the plugin updates. If it didn't succeed, click **Update Runtime** to manually trigger --- ## 3. Quickstart ```bash # 1. Export from Zotero (Better BibTeX JSON, Keep updated) to exports/ # 2. Sync paperforge sync # 3. Mark a paper for OCR in its frontmatter: do_ocr: true # 4. Run OCR paperforge ocr # 5. Mark for deep reading: analyze: true # 6. In your Agent chat: /pf-deep ``` --- ## 文档导航 | 你想做什么 | 去看 | | ------------------------------------------ | ------------------------------ | | 完整教程，从安装到精读 | [使用教程](docs/getting-started.md) | | 遇到问题了 | [故障排除](docs/troubleshooting.md) | | 查某个命令 | [命令参考](docs/COMMANDS.md) | | 如何升级 | [更新指南](docs/update-upgrade.md) | | 架构 / 维护 / 发布 | [架构文档](docs/ARCHITECTURE.md) | | AI Agent 协作 | [AGENTS.md](AGENTS.md) | --- ## License [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/). Non-commercial use only. ## Acknowledgments Built on [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR), [Obsidian](https://obsidian.md), [Better BibTeX for Zotero](https://retorque.re/zotero-better-bibtex/), and other great open-source projects.