search

RyotaUshio / obsidian-pdf-plus

PDF++: The most Obsidian-native PDF annotation, viewing & editing tool ever. Comes with optional Vim keybindings.
https://ryotaushio.github.io/obsidian-pdf-plus/
MIT License
824 stars 15 forks source link
obsidian obsidian-plugin pdf pdf-annotation pdf-editor pdf-generation pdf-viewer vim

readme

Obsidian PDF++

Obsidian Downloads

[!note] All contribution to this plugin has been made by a single voluntary student (me).

  • If you like this plugin, don't forget to star this repository!
  • If this plugin has become an important piece of your workflow, please consider donation to show some love for this project.

Both are greatly appreciated. Thank you!

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

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

🚀 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.
  • You need Obsidian v1.5.8 or higher to receive updates from PDF++. Otherwise, you will be stuck at the last PDF++ version (0.40.4) that supported older versions of Obsidian.

[!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.

image

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.

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.

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.

Opening links to PDF files

Open PDF links cleverly

Other options

Copying links to PDF files

Copy links with ease

Copy PDF internal links as Obsidian links

See here for the details.

Link copy templates

You can customize the template format that will used when copying a link to a selection or an annotation in PDF viewer. Each {{...}} in the template will be evaluated as a JavaScript expression with many variables available. See the plugin settings for the details.

Right-click menu options

Customize the behavior of Obsidian\'s built-in right-click menu in PDF view.

Copy link to section from PDF outline (table of contents)

Copy link to page from PDF thumbnail

Embedding PDF files

Keyboard shortcut commands

PDF++ offers the following commands for reducing mouse clicks on the PDF toolbar by assigning hotkeys to them.

Integration with external apps (desktop-only)

Misc

CSS customization

You can customize the styling of various components of PDF++ using CSS snippets.

Text highlights

Here is a list of CSS selectors to target:

Callout colors

The highlight colors that you define in the Highlight colors setting are also available as CSS variables. For example, a color named "Yellow" will be converted into a variable --pdf-plus-yellow-rgb. Its value is a tuple of the RGB values, e.g. 255, 208, 0. Note that non-alphanumeric characters are replaced with hyphens in variable names. For example, a color with name "Super LONG name!!" will result in a variable name --pdf-plus-super-long-name-rgb.

Additionally, the color specified in the Default highlight color setting is also available as --pdf-plus-default-color-rgb.

You can use these CSS variables for various purposes. For example, you can create a callout whose color matches the highlight color in the PDF viewer.

1. Different colors within a single callout type

Here we use a callout type "PDF" as an example, but it can be anything you like.

Copy format:

> [!PDF|{{colorName}}] {{linkWithDisplay}}
> {{text}}

Result example:

> [!PDF|yellow] [[file.pdf#page=1&selection=0,1,2,3&color=yellow|file, page 1]]
> Lorem ipsum

> [!PDF|red] [[file.pdf#page=1&selection=0,1,2,3&color=red|file, page 1]]
> Lorem ipsum

> [!PDF|] [[file.pdf#page=1&selection=0,1,2,3|file, page 1]]
> Lorem ipsum

or without pipe ("|") after the callout type ("PDF"):

> [!PDF] [[file.pdf#page=1&selection=0,1,2,3|file, page 1]]
> Lorem ipsum

CSS snippet:

.callout[data-callout="pdf"][data-callout-metadata="yellow"] {
    --callout-color: var(--pdf-plus-yellow-rgb);
}

.callout[data-callout="pdf"][data-callout-metadata="red"] {
    --callout-color: var(--pdf-plus-red-rgb);
}

.callout[data-callout="pdf"] {
    --callout-color: var(--pdf-plus-default-color-rgb);
}

2. Color by callout types

Another approach is to associate each highlight color to a specify callout type such as "Note" or "Important".

Copy format:

> [!{{colorName}}] {{linkWithDisplay}}
> {{text}}

Result example:

> [!note] [[file.pdf#page=1&selection=0,1,2,3&color=note|file, page 1]]
> Lorem ipsum

> [!important] [[file.pdf#page=1&selection=0,1,2,3&color=important|file, page 1]]
> Lorem ipsum

CSS snippet:

.callout[data-callout="note"] {
    --callout-color: var(--pdf-plus-note-rgb);
}

.callout[data-callout="important"] {
    --callout-color: var(--pdf-plus-important-rgb);
}

Popover preview of PDF internal links

Sometimes, You may find preview popovers too tall.

For example, suppose you're reading a LaTeX-generated paper. You can hover over an inline citation (e.g. "Author et al., 2024") to show a popover preview of the corresponding entry in the bibliography section. Since a bib entry is not that tall, the popover often has too much vertical space.

Now, use the following CSS snippet to remove the extra space:

.pdf-plus-pdf-internal-link-popover[data-dest^="cite."] {
    --my-height: 200px; /* Change this to your liking */
    height: var(--my-height) !important;
    top: calc(var(--popover-height) - var(--my-height)) !important;
}

The data-dest attribute is the ID of the named destination (i.e. link target) that the internal link points to, which starts with cite. for bibliographic items. In general, you can get the ID by the following steps:

You can also find a great tutorial on the forum.

Note on saving annotations directly in PDF

Although PDF++ is primarily designed with backlink highlighting (= annotation by backlink) in mind, it is also possible to add annotations directly inside PDF files. However, you will notice some limitations, including the viewer being reloaded every time you add a highlight to your file. Therefore, this feature should be considered to be a temporary workaround until Obsidian itself supports PDF annotation, which is on their roadmap.

Update 2024-08-20: I've just found a new plugin called Pdf Annotator. For now, it does not save annotations in PDF itself. However, it says it will be able to do so once Obsidian's PDF.js version is updated to 4.x. For those who prefer in-file annotations to backlink highlighting, this might be a better solution. Fortunately, it seems to be compatible with PDF++, meaning you can use features from both of two plugins at the same time although some of PDF++ features (e.g. hover over a highlight to preview backlinks, double-click on a highlight to open backlinks, etc.) are not available for annotations made by the Pdf Annotator plugin.

Installation

You can install this plugin from within Obsidian's community plugin browser.

Alternatively, you can try the cutting-edge, latest beta release using BRAT.

  1. Install the latest version of BRAT and enable it.
  2. (Optional but highly recommended) In the BRAT settings, turn on Auto-update plugins at startup at the top of the page.
  3. Open the following URL in the browser: obsidian://brat?plugin=RyotaUshio/obsidian-pdf-plus.
  4. Click the "Add Plugin" button.

Credits

PDF++ is built on top of Obsidian's native PDF viewer powered by Mozilla's PDF.js, which is already pretty good even without PDF++. Without the awesome work of the Obsidian team and the PDF.js maintainers, PDF++ would not have been possible.

PDF++ extends the native viewer by using monkey-around, an awesome patching library by PJ Eby. It is used by countless Obsidian plugins and has been helping the community as an infrastructure providing a foundation of Obsidian's high extendability. He's also the author of several popular Obsidian plugins including Tag Wrangler.

PDF++ offers two ways to highlight text in PDF: one that does not involve modifying the PDF file, and the other that writes highlight annotations directly into the PDF file. The latter is powered by the pdf-lib, a JavaScript library for creating and modifying PDF documents. The original project was created by Andrew Dillon. PDF++ uses a forked version maintained by Cantoo Scribe.

PDF++ also supports Vim-like keybindings. Its design was inspired by codemirror-vim and Tridactyl. Especially, some code for the link mode was borrowed from Tridactyl, which is distributed under the Apache 2.0 License by Colin Caine, Oliver Blanthorn and Koushien with some modification.

Compatibility

I'm trying to keep PDF++ compatible with the following plugin(s) as much as possible:

The following plugin(s) alters Obsidian's internals in such a way that prevents some aspects of other plugins from working properly, so I don't recommend using it together with this plugin.

Development principles

Support development

If you find my plugins useful, please support my work to ensure they continue to work!

GitHub Sponsors

Buy Me A Coffee

Buy Me a Coffee at ko-fi.com