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](https://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](#note-on-saving-annotations-directly-in-pdf)).
- 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](https://github.com/elias-sundqvist/obsidian-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](#installation)
[Read the docs](https://ryotaushio.github.io/obsidian-pdf-plus/) (Note: it's still a work in progress!)
[Ask & answer questions](https://github.com/RyotaUshio/obsidian-pdf-plus/discussions)
❗ [Report bugs](https://github.com/RyotaUshio/obsidian-pdf-plus/issues/new/choose) (Tip: when something is not working, first restart Obsidian by running the `Reload app without saving` command.)
> [!note]
> - Some features require the [Style Settings](https://github.com/mgmeyers/obsidian-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](https://play.google.com/store/apps/details?id=com.google.android.webview&hl=en) (if you are on Android 7-9, update [Chrome](https://play.google.com/store/apps/details?id=com.android.chrome&hl=en) 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](https://github.com/RyotaUshio/obsidian-pdf-plus/discussions/48)). 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](#features) 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](https://github.com/nothingislost/obsidian-hover-editor)
It's also friendly to laptops with small display sizes.
See [here](https://github.com/RyotaUshio/obsidian-pdf-plus/wiki/Tips:-My-display-is-too-small!#blazingly-fast--smooth-workflow-with-hover-editor) for the details.
https://github.com/RyotaUshio/obsidian-pdf-plus/assets/72342591/cb292049-bd89-4cd1-9d72-a02828d765e0
#### Transform the [backlinks pane](https://help.obsidian.md/Plugins/Backlinks) into [ZotLit](https://zotlit.aidenlx.top/)-like annotation view with [Better Search Views](https://github.com/ivan-lednev/better-search-views) & PDF++ callouts
See [here](https://github.com/RyotaUshio/obsidian-pdf-plus/wiki/Tips:-backlinks-pane) 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://ryotaushio.github.io/obsidian-pdf-plus/embedding-rectangular-selections.html)
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](https://help.obsidian.md/Plugins/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](#editing-pdf-files-directly-experimental).
- **Custom highlight colors**: Append `&color=` to a link text to highlight the selection with a specified color.
- `` 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](https://help.obsidian.md/Editing+and+formatting/Callouts) with the same color as the highlight color without any CSS snippet scripting.
#### [Backlink pane](https://help.obsidian.md/Plugins/Backlinks) 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](https://help.obsidian.md/Plugins/Backlinks).
- **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](https://github.com/RyotaUshio/obsidian-pdf-plus/issues/new).
### 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](https://github.com/RyotaUshio/obsidian-pdf-plus/wiki/Page-labels)
### 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](#css-customization) 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](https://help.obsidian.md/User+interface/Use+tabs+in+Obsidian#Open+a+link), 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"), d