mirror of
https://github.com/lllin000/PaperForge.git
synced 2026-07-22 06:50:53 +00:00
97a2875d48
Separate audiences: README as navigation entry, getting-started as canonical tutorial, troubleshooting as failure recovery, AGENTS as agent-only operating contract, COMMANDS as pure reference, maintainer-guide for release/versioning/architecture.
108 lines
4.1 KiB
Markdown
108 lines
4.1 KiB
Markdown
<p align="center">
|
|
<img src="docs/images/paperforge-banner.png" alt="PaperForge banner" width="100%" />
|
|
</p>
|
|
|
|
# PaperForge
|
|
|
|
[](https://github.com/LLLin000/PaperForge/releases)
|
|
[](https://python.org)
|
|
[](LICENSE)
|
|
|
|
[简体中文](README.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: BRAT (Recommended)
|
|
|
|
1. Install **BRAT** from the Obsidian community plugin browser
|
|
2. Open BRAT settings → `Add Beta Plugin`
|
|
3. Enter: `https://github.com/LLLin000/PaperForge`
|
|
4. BRAT downloads the latest `main.js`, `manifest.json`, and `styles.css` and installs them
|
|
5. Settings → Community Plugins → enable PaperForge
|
|
|
|
> BRAT auto-detects GitHub Release updates. No manual downloads needed.
|
|
|
|
### Option B: 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 <zotero_key>
|
|
```
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
| If you want to | Read |
|
|
| --------------------------------------- | ----------------------------------------- |
|
|
| Full tutorial, from install to deep read | [Getting Started](docs/getting-started.md) |
|
|
| Troubleshooting | [Troubleshooting](docs/troubleshooting.md) |
|
|
| Command reference | [Commands](docs/COMMANDS.md) |
|
|
| How to update | [Update Guide](docs/update-upgrade.md) |
|
|
| Architecture / Maintenance / Release | [Architecture](docs/ARCHITECTURE.md) |
|
|
| AI Agent collaboration | [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.
|