Obsidian PDF++

[!note] I’m currently working on PDF++ v1.0.0. Because this release involves extensive refactoring, you probably won’t see any major updates for a few months—aside from minor bug fixes—until I can ship the 1.0.0 beta. But don’t worry: there’s a lot going on under the hood!

⭐ Star this repo to show your support!

This is an Obsidian.md plugin for a better PDF experience. Specifically:

• It transforms backlinks to PDF files into highlight annotations, i.e. you can annotate PDF files with highlights just by linking to text selection.
• Alternatively, you can add annotations directly into PDF files so that they are also visible outside Obsidian (but with limitations; see here).
• Moreover, it adds many quality-of-life improvements to the built-in PDF viewer and PDF embeds. So it's useful even if you don't use it as an annotation tool (you can even turn off the annotation functionality!).

PDF++ stands out among other PDF annotation tools for the following reasons:

• PDF++ acts as a complement to Obsidian's native PDF viewer rather than replacing it. It allows you to make sidenotes as pure markdown, so you will not lose your annotations even if the plugin stops working as long as Obsidian is alive. It will not leave behind a pile of unreadable JSON even if this plugin stops working in the future, unlike Annotator.

  I'm not a fan of .md files that are actually not markdown at all. The value of the markdown format does not lie in the file extension!

• PDF++ makes Obsidian work as a stand-alone PDF annotation tool. You can seamlessly annotate your PDFs using Obsidian's rich markdown editor without switching between Obsidian and an external app like Zotero or Marginnote.
• Annotations for a single PDF are no longer confined to a single file and can be distributed across the whole vault. It establishes a novel, Obsidian-native way of PDF annotation.
• PDF++ does not introduce plugin-dependent syntaxes except for a few optional ones (&color=.../&rect=... link parameters).

🚀 Install

📖 Read the docs (Note: it's still a work in progress!)

💬 Ask & answer questions

❗ Report bugs (Tip: when something is not working, first restart Obsidian by running the Reload app without saving command.)

[!note] - Some features require the Style Settings plugin enabled. - In the near future, you will need Obsidian v1.6.5 or higher to receive updates from PDF++. Otherwise, you will be stuck at the last PDF++ version that supported older versions of Obsidian. - If you're an Android user and have trouble with PDF++, first try updating Android System WebView (if you are on Android 7-9, update Chrome instead).

[!warning] This plugin relies on many private APIs of Obsidian, so there is a relatively high risk that this plugin may break when Obsidian is updated (learn more). For this reason, I hope this plugin's functionalities will be natively supported by Obsidian itself so that we won't need this plugin anymore.

Getting started

Here I'm just scratching the surface of what PDF++ can do. See below and the plugin settings in Obsidian for more details. Also note that each feature can be toggled on and off in the plugin settings, which lets you customize this plugin to best fit into your use case.

Link to PDF files to annotate them with highlights

https://github.com/RyotaUshio/obsidian-pdf-plus/assets/72342591/0a9c267d-b74a-4568-821b-a659e29fdac0

Color palette for easily copying links & specifying highlight colors

https://github.com/RyotaUshio/obsidian-pdf-plus/assets/72342591/72072345-3537-42e7-ad06-5e4a166f83f4

Copy links quickly via a hotkey

https://github.com/RyotaUshio/obsidian-pdf-plus/assets/72342591/8ef3bc62-70d7-449a-b6a7-0370a2b4a8d8

Seamless integration with other community plugins

Blazingly fast workflow with Hover Editor

It's also friendly to laptops with small display sizes. See here for the details.

https://github.com/RyotaUshio/obsidian-pdf-plus/assets/72342591/cb292049-bd89-4cd1-9d72-a02828d765e0

Transform the backlinks pane into ZotLit-like annotation view with Better Search Views & PDF++ callouts

See here for the details.

Highly customizable copy formats

https://github.com/RyotaUshio/obsidian-pdf-plus/assets/72342591/fb624769-4cc3-4d4e-9898-b17d0a5591e3

Rectangular selection embeds

Learn more

https://github.com/RyotaUshio/obsidian-pdf-plus/assets/72342591/7a6331ab-71bf-45d0-a457-7984e487e326

Ctrl/Cmd+hover over highlights to preview or open backlinks

Depends on the Action when hovering over highlighted text setting.

Preview

https://github.com/RyotaUshio/obsidian-pdf-plus/assets/72342591/ea14d06a-70f6-45cf-a142-0213adb9749b

Open

https://github.com/RyotaUshio/obsidian-pdf-plus/assets/72342591/5f3dded8-79ad-44cc-816f-dc697dc4a343

Filter backlinks by page

Show only backlinks to the page that is currently opened in the PDF viewer.

https://github.com/RyotaUshio/obsidian-pdf-plus/assets/72342591/4147e634-7864-40b4-b916-a6db40b85f31

"Hover sync" between PDF viewer & backlinks pane

https://github.com/RyotaUshio/obsidian-pdf-plus/assets/72342591/2285a837-0588-4a72-8193-da25a456bf84

Features

Each feature can be toggled on and off in the plugin settings.

Backlink highlighting

Annotate PDF files with highlights just by linking to text selection. You can easily copy links to selections using color palette in the toolbar. See the "Color palette" section for the details.

• Highlight backlinks in PDF viewer: In the PDF viewer, any referenced text will be highlighted for easy identification.
• By default, all backlinks are highlighted. However, there is an option that allows you to highlight only backlinks with colors specified in the link text (see below).
• It does not modify the PDF file itself. It just changes how the file content is displayed in Obsidian. PDF++ also offers an option to add highlights to PDFs directly.
• Custom highlight colors: Append &color=<COLOR NAME> to a link text to highlight the selection with a specified color.
• <COLOR NAME> is one of the colors that you register in the plugin settings. e.g [[file.pdf#page=1&selection=4,0,5,20&color=red]]
• Color names are case-insensitive, i.e. all of &color=red, &color=RED and even &color=rEd work the same.
• You can use the color palette in PDF toolbars to easily copy links with &color=... appended automatically. See the "Color palette" section for the details.
• You can also opt not to use this plugin-dependent notation and apply a single color (the "default highlight color" setting) to all highlights.
• Easily navigate to backlinks by pressing Ctrl/Cmd (by default) while hovering over a highlighted text in PDF viewer: you can choose what happens when you hover over a highlighted text between the following:
• Open backlink
• Popover preview of backlink
• Double click a piece of highlighted text to open the corresponding backlink

PDF++ callouts

Create callouts with the same color as the highlight color without any CSS snippet scripting.

Backlink pane improvements

These features make Obsidian a unique PDF annotation tool that tightly connects PDFs to your ideas stored as markdown files.

• Filter backlinks by page: Show only backlinks to the page that is currently opened in the PDF viewer.
• Hover sync (PDF viewer → Backlinks pane): Hovering over highlighted text or annotation will also highlight the corresponding item in the backlink pane.
• Hover sync (Backlinks pane → PDF viewer): In the backlinks pane, hover your mouse over a backlink item to highlight the corresponding text or annotation in the PDF viewer.

Editing PDF files directly (experimental)

Add, edit, and delete highlights and links in PDF files. Added annotations will be visible even outside Obsidian, unlike backlink highlights.

PDF++ will not modify PDF files themselves unless you explicitly allow it. The author assumes no responsibility for any data corruption. Please make sure you have a backup and use it at your own risk. Report any issues you encounter here.

PDF page composer: PDF counterpart of the "Note Composer" core plugin

Add, insert, remove or extract PDF pages via commands and automatically update related links in the entire vault.

Add, rename, move and delete PDF outline items (a.k.a. table of contents / bookmarks)

Allow PDF modification and right-click on the PDF outline. Alternatively, you can use the command "Add to outline" to add a new item, or drag & drop outline items to move it under another item.

Edit page labels

Learn more

PDF internal links enhancement

Make it easier to work with internal links embedded in PDF files.

• Show a popover preview of PDF internal links by hover+command/ctrl: See below for advanced CSS customization.
• Enable history navigation for PDF internal links: When enabled, clicking the "navigate back" (left arrow) button will take you back to the page you were originally viewing before clicking on an internal link in the PDF file.
• Copy PDF link as Obsidian link: (Requires custom right-click menu enabled) In the PDF viewer, right-click a PDF-embedded link and then click "Copy PDF link as Obsidian link". It will copy the PDF link as an Obsidian link that you can paste into markdown files. Clicking the pasted link will take you to the same destination as the original PDF link.
• "Copy link to current page view" command: Running this command while viewing a PDF file will copy a link, clicking which will open the PDF file at the current scroll position and zoom level.
• Paste copied link to a text selection in a PDF file: (Requires custom right-click menu & PDF editing enabled) After copying a link by the above actions, you can "paste" it to a selection in PDF to create a PDF internal link. To do this, right-click the selection and click "Paste copied link to selection".

Opening links to PDF files

Open PDF links cleverly

• Don't open a single PDF file in multiple tabs: When opening a link to a PDF file without pressing any modifier keys, a new tab will not be opened if the same file has already been opened in another tab. Useful for annotating PDFs using a side-by-side view ("Split right"), displaying a PDF on one side and a markdown file on another.
• You can optionally highlight the existing tab to enhance visual feedback.
• Open PDF links next to the existing PDF tab: If there is a PDF file opened in a tab, clicking a PDF link will first create a new tab next to it and then open the target PDF file in the created tab. This is especially useful when you are splitting the workspace vertically or horizontally and want PDF files to be always opened on one side.
• Don't move focus to PDF viewer after opening a PDF link
• Open PDF links with an external app: See below for the details.

Other options

• Always record navigation history when opening PDF links: By default, the history is recorded only when you open a link to a different PDF file. If enabled, the history will be recorded even when you open a link to the same PDF file as the current one, and you will be able to go back and forth the history by clicking the left/right arrow buttons even within a single PDF file.
• Open PDF link instead of showing popover preview when target PDF is already opened: Press Ctrl/Cmd while hovering a PDF link to actually open it if the target PDF is already opened in another tab.
• Clear highlights after a certain amount of time
• Ignore the height parameter in popover preview: Obsidian lets you specify the height of a PDF embed by appending &height=... to a link, and this also applies to popover previews. Enable this option if you want to ignore the height parameter in popover previews.

Copy