Get help with Eddie Doc

Where to get help

Before you file a bug

A good report gets a fast fix. Please include:

1. The extension or plugin version (VS Code: Extensions view; Obsidian: Settings → Community plugins) and your VS Code or Obsidian version, plus the platform if you are on mobile.
2. What you did, what you expected, and what happened instead.
3. If mapping is wrong: a minimal .adoc and the annotated PDF, or the relevant slice of the <file>.review.json sidecar.
4. Any errors from Help → Toggle Developer Tools → Console.

Troubleshooting

The most common issues, and how to resolve them.

My annotations land under “Unmatched”

The fuzzy matcher couldn't place the marked text above the confidence threshold. Options, in order:

• Put your cursor on the right line and run Eddie Doc: Re-link to Current Cursor Line, or use the Triage button on the Unmatched group to clear them in one pass.
• Lower eddieDoc.matchThreshold (VS Code) or Match threshold (Obsidian) (default 0.5) if many correct matches are being rejected.
• If the source and PDF have diverged a lot, enable the semantic fallback (below).

“Semantic fallback couldn't reach Ollama”

The optional embedding fallback is on but no Ollama server answered. Either start Ollama with the model pulled (ollama pull embeddinggemma), point eddieDoc.ollamaUrl at the right host, or turn the feature off with eddieDoc.semanticFallback: false. It is off by default.

Nothing is extracted from my PDF

Eddie Doc reads real PDF markup annotations (highlights, strikethroughs, comments, carets). If your PDF was flattened or printed-to-PDF, the marks are baked into the page image and can't be recovered — re-export keeping annotations live. Reply annotations and empty marks with no comment are skipped by design.

A delete/replace changed more (or less) text than the mark

Character-precise edits use markedText aligned back through AsciiDoc markup. If a mark only partially covered a word, Eddie Doc snaps to whole words. When in doubt, use Replace struck / highlighted text… to review the exact range before applying.

My resolved state disappeared after re-exporting the PDF

Item ids are derived from annotation geometry, so re-exporting a PDF at different positions can produce new ids. Re-map, then re-link any items that lost their state. The <file>.review.json sidecar is a diffable record — commit it to keep review history.

Eddie Doc for Obsidian

The Obsidian plugin is new and has not yet been tested on real devices; the first release is pending. The user guide has the full troubleshooting list. Common questions:

Does it work on mobile?

It is built to: the plugin is not desktop-only and uses the same code on phones. It has been tested on desktop Obsidian and tried by hand on a phone, and PDF parsing on a phone, especially of a large PDF, may be slow. The PDF must be inside the vault. Choosing a file from disk and the optional Ollama fallback are desktop only.

How does it handle .adoc files?

If no other plugin handles .adoc or .asciidoc, Eddie opens them in the source editor. If another AsciiDoc plugin does, Eddie leaves the extension alone and, when it needs to show the source, opens it in Obsidian's built-in editor in its own tab, beside that plugin's view. The setting Open .adoc files with Eddie (Auto or Never) controls this; reload the plugin after changing it. Eddie does not render AsciiDoc.

Where are my reviews stored?

In Eddie Reviews/ at the root of the vault, as Eddie Reviews/<manuscript path>/<doc>/rev-N/<mapping>.review.json. The folder is visible on purpose, because Obsidian does not index or sync folders that start with a dot. Annotated PDFs are copied into it.

How do I sync them, and can I use them in VS Code?

The review folder is an ordinary folder, so your usual sync or git setup handles it. The plugin does not reload a sidecar changed on another device while it is running; reload the plugin after a sync, and avoid editing the same round on two devices at once. The files are the same format as the VS Code extension and CLI write (Review Format).

The sidecar looks different after this version

Eddie Doc migrated it to Review Format v2 automatically on the first save. Version-1 sidecars are read transparently; no action needed. See the changelog.

Shape the roadmap

An issue fixes one thing. The survey tells us what to work on at all.

Five minutes, and you can skip any question: how satisfied you are, which of the sixteen features you actually use, how well annotations map to your source, and what you most want added.

Useful links