94 lines
3.1 KiB
Markdown
94 lines
3.1 KiB
Markdown
# org-to-quartz: Org Notes to Quartz Converter
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
org-notes-quartz/
|
|
├── flake.nix
|
|
├── pyproject.toml
|
|
├── AGENTS.md
|
|
├── PLAN.md
|
|
└── src/
|
|
└── org_to_quartz/
|
|
├── __init__.py
|
|
├── main.py # CLI (argparse)
|
|
├── org_parser.py # Parse #+key: values + body
|
|
├── markdown_writer.py # YAML front matter + pandoc conversion
|
|
├── image_handler.py # Detect & copy images per-note
|
|
└── citations/
|
|
├── __init__.py
|
|
├── resolver.py # Orchestrator: tries resolvers in order
|
|
├── zotero.py # Better BibTeX JSON-RPC (port 23119)
|
|
├── bibtex.py # pybtex to parse local .bib
|
|
└── doi.py # Format as DOI link fallback
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
- Python 3.11+
|
|
- pandoc (org → gfm conversion)
|
|
- pybtex (parse .bib files)
|
|
- requests (Zotero JSON-RPC)
|
|
|
|
## Module Responsibilities
|
|
|
|
| Module | Responsibility |
|
|
|--------|----------------|
|
|
| `main.py` | CLI: `org-to-quartz <input_dir> <output_dir> [--bib FILE]` |
|
|
| `org_parser.py` | Extract front matter dict + body text from `.org` |
|
|
| `markdown_writer.py` | Build YAML front matter, call pandoc, write `.md` |
|
|
| `image_handler.py` | Find `[[file:img.png]]` / `./img.png`, copy to `<note>/` |
|
|
| `citations/resolver.py` | Chain: Zotero → Bibtex → DOI, return `[Author, Year](zotero://...)` |
|
|
| `citations/zotero.py` | JSON-RPC to `http://localhost:23119/better-bibtex/json-rpc` |
|
|
| `citations/bibtex.py` | Parse `.bib`, format author/year, link to DOI if available |
|
|
| `citations/doi.py` | Format `[cite_key](https://doi.org/...)` or raw key |
|
|
|
|
## Output Structure
|
|
|
|
```
|
|
content/
|
|
├── my-note/
|
|
│ ├── index.md # The converted note
|
|
│ └── diagram.png # Copied image
|
|
├── another-note/
|
|
│ ├── index.md
|
|
│ └── photo.jpg
|
|
```
|
|
|
|
## Front Matter Mapping
|
|
|
|
| Org | YAML |
|
|
|-----|------|
|
|
| `#+title:` | `title:` |
|
|
| `#+filetags:` | `tags:` (list) |
|
|
| `#+date:` | `date:` |
|
|
| `#+hugo_lastmod:` | `lastmod:` |
|
|
| `#+hugo_tags: noexport` | `draft: true` + TODO comment |
|
|
|
|
## Citation Flow
|
|
|
|
```
|
|
cite:smith2020 → Zotero JSON-RPC lookup
|
|
├─ Found → [Smith, 2020](zotero://select/items/@smith2020)
|
|
└─ Not found → Bibtex lookup
|
|
├─ Found → [Smith, 2020](https://doi.org/10.xxx)
|
|
└─ Not found → DOI resolver
|
|
└─ [smith2020] (raw)
|
|
```
|
|
|
|
## Implementation Order
|
|
|
|
1. `flake.nix` + `pyproject.toml` - project skeleton
|
|
2. `org_parser.py` - front matter + body extraction
|
|
3. `markdown_writer.py` - pandoc integration + YAML output
|
|
4. `image_handler.py` - image detection and copying
|
|
5. `citations/bibtex.py` - local bib parsing
|
|
6. `citations/doi.py` - simple fallback formatter
|
|
7. `citations/zotero.py` - JSON-RPC client
|
|
8. `citations/resolver.py` - orchestrator
|
|
9. `main.py` - CLI wiring
|
|
|
|
## TODO
|
|
|
|
- [ ] Handle org-roam `id:` links (requires ID→title mapping from all files)
|