85 lines
3.4 KiB
Markdown
85 lines
3.4 KiB
Markdown
# Obsidian Integration Notes
|
|
|
|
Use these rules when the Zotero AI notes workflow touches the user's Obsidian vault. They are adapted from the Obsidian skill patterns in `kepano/obsidian-skills`, but scoped to this Zotero note workflow.
|
|
|
|
## Scope
|
|
|
|
- The Zotero child note is the primary output.
|
|
- The Obsidian vault provides templates, prompts, and local workflow state.
|
|
- Vault-facing files should be lightweight. Do not copy PDFs, Zotero attachments, large corpora, or API keys into the skill or vault helper files.
|
|
|
|
## Markdown Compatibility
|
|
|
|
Preserve Obsidian Flavored Markdown when reading templates or generating vault-facing Markdown:
|
|
|
|
- Wikilinks: `[[Note]]`, `[[Note#Heading]]`, `[[Note|Display Text]]`
|
|
- Embeds: `![[file.pdf#page=3]]`, `![[image.png|300]]`
|
|
- Callouts: `> [!note]`, `> [!warning] Custom Title`, foldable `> [!faq]-`
|
|
- Tags: `#tag`, `#nested/tag`, or YAML `tags`
|
|
- Highlights: `==important text==`
|
|
- Comments: `%%hidden text%%`
|
|
- Math: `$inline$` and `$$block$$`
|
|
- Mermaid code blocks when the template already asks for diagrams
|
|
|
|
Do not normalize these into plain Markdown if the content is meant to return to Obsidian.
|
|
|
|
## Properties / Frontmatter
|
|
|
|
If this skill creates auxiliary `.md` files in the vault, add YAML frontmatter only when it adds real value. Keep it simple and valid:
|
|
|
|
```yaml
|
|
---
|
|
title: Zotero AI Notes Audit
|
|
tags:
|
|
- zotero
|
|
- ai-notes
|
|
status: generated
|
|
---
|
|
```
|
|
|
|
Use these property conventions when needed:
|
|
|
|
- `title`: human-readable note title
|
|
- `tags`: searchable labels such as `zotero`, `ai-notes`, `literature`
|
|
- `aliases`: only for names the user would naturally search
|
|
- `zotero_key`: item key or parent item key when a file represents one Zotero item
|
|
- `doi`: DOI when known
|
|
- `status`: small workflow state such as `missing-note`, `generated`, `needs-review`
|
|
|
|
Avoid storing secrets, raw API responses, or full prompts in frontmatter.
|
|
|
|
## Template Round-Trip Rules
|
|
|
|
- `01 ...md` is the research-article template.
|
|
- `02 ...md` is the review-article template.
|
|
- `03 ...md` is the LLM prompt used to fill literature notes.
|
|
- Keep the user's headings and placeholders intact unless the requested task is template redesign.
|
|
- If a generated Zotero note looks wrong, inspect the corresponding template before changing Python logic.
|
|
- If the template includes Obsidian-only syntax, let it pass through unless Zotero rendering breaks in practice.
|
|
|
|
## Audit And Index Files
|
|
|
|
The fast audit cache currently lives at:
|
|
|
|
```text
|
|
<vault>\00 Templater\.zotero-ai-notes-index.json
|
|
```
|
|
|
|
Rules:
|
|
|
|
- Use the JSON cache for deterministic missing-note checks.
|
|
- Do not ask an LLM to compare Zotero library state.
|
|
- Rebuild the cache after external note edits or major Zotero changes.
|
|
- If a user wants a human-readable vault dashboard later, create a separate Markdown or `.base` export from the cache instead of replacing the JSON cache.
|
|
|
|
## Future Upgrade Hooks
|
|
|
|
Good follow-up extensions:
|
|
|
|
- `--export-missing-md`: write an Obsidian note listing Zotero items still missing generated notes.
|
|
- `--export-base`: create an Obsidian Bases `.base` view over generated audit Markdown files.
|
|
- `--open-vault-note`: optionally call Obsidian CLI when installed and Obsidian is already open.
|
|
- `--template-version`: record which template version generated a note, without adding visible banners to Zotero notes.
|
|
|
|
Keep these as optional features. The default workflow should remain Zotero-first and script-driven.
|