Foxycape PDF

A PDF reader for Obsidian that stays connected to your notes — highlights, citations, and deep links that take you back to the source.

English | 中文

Why

Reading PDFs inside Obsidian often breaks the note-taking loop:

• Highlights stay in the PDF; your vault notes stay elsewhere.
• Grabbing a figure usually means a blurry screenshot.
• Pasted quotes and images rarely point back to the exact page or region.
• Light PDF pages feel harsh in a dark vault theme.
• Switching readers can break page/selection links you already use.

Foxycape PDF addresses these gaps without asking you to leave Obsidian.

Features

Highlight → note sync

Instead of leaving highlights stranded in the PDF, each new highlight can create or update a Markdown note with the same name, append the excerpt with a back-link, and optionally open that note in a split pane. Turn it off anytime in settings.

Extract embedded images

Skip blurry screenshots. Hover an embedded image (or use the touch control on mobile) to preview, copy, or download the original asset.

Cite text and images, then jump back

Citations stay tied to the source, so you can jump back from the note later:

• Copy a text citation as Markdown with a deep link (#page= / #selection= / #markId=).
• Copy an image citation; paste into Markdown to save a PNG next to the PDF and insert a clickable link.
• Right-click the note image → Open in Foxycape to return to the page and highlight the original region.

Theme-aware PDF pages

Bright PDF pages can fight a dark vault. Optionally remap grayscale vector colors to your theme foreground/background (BETA) — for all themes, dark only, or light only. Color artwork stays as-is.

Region screenshot

Skip the OS snipping tool, and skip stitching pages by hand. Click Screenshot in the toolbar and drag a region on the PDF. Copy the image, or copy an image citation so you can jump back from the note later.

Crop a region on a single page:

Span the page gap and Foxycape stitches it into one continuous image:

Compatible with Obsidian’s built-in PDF links

Switching readers shouldn’t break the links you already have. Foxycape understands Obsidian-style #page= and #selection=, can become the default PDF viewer, reuses an open tab when possible, and adds #markId= for precise highlight jumps.

Highlights and highlight list

Highlighter, wavy underline, and straight underline with custom colors. Browse highlights in a list — filter, sort, jump, or delete.

Smart copy — unwrap soft line breaks

PDF lines often insert hard breaks mid-sentence. Select text and copy as usual: Foxycape strips those soft wraps so the paste reads as continuous prose, while keeping real paragraph breaks.

Navigation and search

Outline (TOC), page thumbnails, page picker, and in-document search (Mod+F) with case / diacritic / whole-word options. Search uses the PDF text layer (no OCR).

Reading layout

Zoom (auto / page width / percentages), vertical or horizontal scroll, single / facing / book layout, page rotation, password-protected PDFs. Works on desktop and mobile.

Set as the default PDF reader

For the smoothest experience—deep links, highlights, and theme-aware pages—turn on Use as default PDF viewer in Foxycape settings so Obsidian opens PDFs with Foxycape by default.

Develop

git submodule update --init --recursive   # if vendor/core is checked out as a submodule
npm install
npm run build      # → dist/main.js, styles.css, manifest.json + foxycape-pdf-assets.zip
npm run dev        # watch build (copies pdfjs/static sidecars into dist/)
npm test
npm run typecheck
npm run link       # junction dist/ into your vault's .obsidian/plugins/foxycape-pdf

Set OBSIDIAN_PLUGIN_DIR to override the vault plugin path used by npm run link.

Community installs only receive the three Obsidian files. Worker and signer are unpacked from main.js on first load (no download). Cmaps and standard fonts (~1.5 MB) download silently from foxycape-pdf-assets.zip when missing — keyed by PDF.js version, so routine plugin upgrades skip the fetch. Local npm run link already has those sidecars under dist/, so no download is needed.

Release (Obsidian Community)

1. Bump version in package.json (semver x.y.z). Build syncs it into manifest.json / versions.json.
2. Commit, then create a GitHub release whose tag equals that version (e.g. 3.3.6, no v prefix).
3. Attach dist/main.js, dist/manifest.json, dist/styles.css, and dist/foxycape-pdf-assets.zip.

Pushing a version tag runs .github/workflows/release.yml, which builds and uploads those assets.

License

This repository is source available under the Foxycape Plugins License Agreement.

• You may use, modify, and redistribute the code, with a restriction on general-purpose competing Obsidian (or similar) offerings — including free public listings that strip trial/license controls.
• Private use, internal use within a single organization, and bespoke client-specific work remain allowed.
• For rights beyond that Agreement, see pricing or contact [email protected].

Third-party components (for example PDF.js) and separately published packages (for example @foxycape/core under MIT) keep their own licenses.

See LICENSE.md for the full text.