How to edit PDF annotations in Obsidian

Create highlights, underlines, note annotations, text annotations (text typed on the page), image annotations, and ink annotations (freehand strokes), change annotation colors, comments, and tags, adjust annotation positions, or delete annotations from Obsidian.

Before you edit

Open the item's PDF in Obsidian. See Open an item's PDF in Obsidian for the available entry points.

Reading annotations needs no setup. Editing needs four things:

1. Zotero 10 or later. With Zotero 9, the PDF opens and shows its annotations, but you cannot change them from Obsidian. ZotLit shows Zotero version is not supported and asks you to update Zotero.
2. Zotero is running. ZotLit sends each change to Zotero and cannot edit annotations while Zotero is closed. Keep Zotero open while you edit.
3. Zotero lets other applications connect to it. In Zotero, open Settings → Advanced and turn on Allow other applications on this computer to communicate with Zotero. When this option is off, ZotLit shows Enable communication with Zotero.
4. ZotLit has your permission to edit. You give it once, as described below.

To give ZotLit permission to change annotations in Zotero, select Allow editing. It is in two places:

• In the annotation view, select the mode button at the start of the view's toolbar, then select Allow editing.
• In Settings > ZotLit > Zotero > Connection, on the Zotero editing row, select Allow editing.

Zotero opens its permission dialog at once. In the dialog, choose Always Allow. ZotLit edits only with a permission that Zotero remembers, so Allow leaves editing off. To decline, choose Deny.

While Zotero waits for your answer, the PDF reader toolbar shows Waiting for approval in Zotero.

Locked annotations

Some annotations are read-only in Obsidian, as they are in Zotero's reader. Their card shows a lock icon beside the page number. Point to the icon to see the reason.

• Zotero imported the annotation from the PDF file. You cannot change or delete it. Zotero imports it again when the file changes, so an edit would be lost.
• In a group library, another member made the annotation. You cannot change it, but you can delete it.

When you select several cards and one of them is locked, a change that the lock refuses applies to none of them.

Create a highlight or underline

1. Select text in the PDF.
2. In the popup, select Highlight or Underline.
3. Wait for the new mark to appear before you continue editing it or switch to Zotero.

The toolbar at the right of the PDF reader provides the same two tools. Select a tool to keep it active, then select text to create marks without using the popup each time. Use the arrow beside a tool to select its color.

To create one highlight in another color, select the text and select a color from the popup. When neither tool is active, a color creates a highlight.

Create a note annotation

Use the note tool to pin a comment to a spot on the page.

1. In the toolbar at the right of the PDF reader, select Add note.
2. Click the page where the note belongs. The note appears centered on the click, and its popup opens with the comment editor ready.
3. Type the comment. It saves as any comment does; see Add or edit a comment.

The tool turns off after each note, as in Zotero. A click on an annotation mark selects that mark instead of creating a note, and a drag creates nothing.

Create a text annotation

Use the text tool to type text onto the page itself.

1. In the toolbar at the right of the PDF reader, select Add text. The tool turns off when the text box opens.
2. Click the page where the text starts. A text box opens at the click.
3. Type the text. Press Enter to start a new line. The box grows to one line of up to 300 pt, then wraps, as in Zotero.
4. Press Escape or click outside the box. The text becomes a text annotation in Zotero, and stays on the page while it saves.

A box that you leave empty creates nothing. A click on an annotation mark selects that mark instead of opening a box. Zotero shows the annotation only when you finish typing, because ZotLit creates it once with its text.

Choose the text color and font size

Select the arrow beside Add text. The menu lists the colors, then the sizes under Font size: 10, 12, 14, 18, 24, and 36 pt. A check mark shows the current color and size. The default size is 14 pt.

ZotLit remembers your color and font size for other PDFs.

Create an image annotation

Use the image tool to capture a figure, a table, or another area without text.

1. In the toolbar at the right of the PDF reader, select Select area.
2. Drag a rectangle around the area. The rectangle stays faint until it is large enough to save.
3. Release the pointer. The new mark appears, and its card shows the captured area.

The tool turns off after each capture. To cancel a drag, press Escape. Press Escape again to turn off the tool. A press on an annotation mark selects that mark instead of starting a rectangle.

Create an ink annotation

Use the ink tool to draw on the page by hand.

1. In the toolbar at the right of the PDF reader, select Draw. The tool starts on blue, Zotero's default ink color.
2. Press on the page and drag. The stroke follows the pointer.
3. Release the pointer. The stroke becomes an ink annotation in Zotero, and stays on the page while it saves.

Each stroke is its own annotation. The tool stays active after each stroke, so you can start the next stroke at once. A tap without movement saves a dot. To combine several strokes into one annotation, merge them in Zotero.

The ink tool works with a mouse, a pen tablet, a trackpad, or a finger on a touchscreen. While the tool is active, a touch drag draws instead of scrolling the page. A stroke draws over text and over other annotation marks, so a press on a mark starts a stroke instead of selecting the mark.

A stroke stays on the page where it started, even if the pointer leaves the page. Zotero limits the size of one annotation. When a long stroke reaches that limit, ZotLit saves the part drawn so far and continues the stroke as a new annotation. You do not need to lift the pointer.

To cancel a stroke, press Escape before you release the pointer. The tool stays active. Press Escape again to turn off the tool. A second finger on the screen during a stroke, as at the start of a pinch zoom, also cancels the stroke.

Choose the ink color and width

Select the arrow beside Draw. The menu lists the colors, then the widths under Size: 0.4, 1, 2, 3, 5, 8, and 12 pt. A check mark shows the current color and width. The default width is 2 pt.

ZotLit remembers your color and width for other PDFs. A stroke keeps the color and width it started with.

Add or edit a comment

1. Select the annotation mark in the PDF. The popup shows the comment under its row of buttons.
2. Select the comment. If the annotation has no comment, select Add a comment…. The cursor goes where you select.
3. Enter the comment. ZotLit saves it as you type.
4. Press Escape or select outside the popup to close the editor.
5. Wait for the comment to save before you edit the annotation in Zotero.

Comments request an automatic save after one second without typing. During continuous typing, ZotLit requests a save after ten seconds from the first unsaved change. Press Enter to add a line break. Press Ctrl+Enter (Windows) or Command+Enter (macOS) to request a save and keep the editor open.

You can also edit the comment on an annotation card. Select the card, and no other card, then select its comment or Add a comment…. Press Escape or select elsewhere in the annotation view to close the editor. When more than one card is selected, a click on a comment only selects the card. The popup and card editors share one draft, so text entered in either editor appears in the other.

If ZotLit detects that the comment changed in Zotero, it shows Changed in Zotero with both versions. Select Use my comment to save your draft over the Zotero comment, or Keep Zotero's comment to discard your draft.

Edit the quoted text

The quoted text of a highlight or underline is the text of the PDF that it marks. Edit it when PDF text extraction got the text wrong, for example with ligatures, split hyphenated words, or wrong symbols. Editing must be enabled; see Before you edit. You edit the quoted text in the annotation view only. The popup in the PDF has no control for it.

1. In the annotation view, select the highlight or underline card, and no other card.
2. Point to the quoted text, and select the pencil button that shows at the end of its first line. The button's tooltip is Edit quoted text. You can also open the card's More options menu, or right-click the card, and select Edit quoted text. The editor opens in the place of the quoted text, with the cursor at the end. A click on the quoted text itself does not open the editor, so you can still select and copy the text.
3. Correct the text. Press Enter to add a line break. Bold, italic, subscript, and superscript use the same keyboard shortcuts as in the comment editor.
4. Press Escape or select elsewhere in the annotation view to save and close the editor.

The quoted text saves as a comment does: after one second without typing, or after ten seconds of continuous typing. Ctrl+Enter (Windows) or Command+Enter (macOS) saves and keeps the editor open. A click outside the annotation view, for example in the PDF, also saves and keeps the editor open. You can save an empty quoted text. The card then shows No quoted text.

The change replaces only the text. The annotation keeps its position and its place in the annotation list order, and Zotero shows the new text. One editing session is one undo step; see Undo and redo a change.

If the quoted text changed in Zotero while you edited it, the card shows Changed in Zotero with both versions. Select Use my text to save your text over the Zotero text, or Keep Zotero's text to discard your text. If a save fails, the card keeps your text. Select Save text to try again.

Change a color

1. Select the annotation mark in the PDF.
2. Select Change color in the popup.
3. Select one of Zotero's annotation colors.

The palette button on an annotation card provides the same colors.

To recolor several annotations at once, select their cards in the annotation view, then press a key from 1 to 8. The keys follow the order of the colors in the palette. One undo reverses the whole group. See Use the annotation view for how to select several cards.

Add or edit tags

1. Select the annotation mark in the PDF.
2. In the popup, select Add tags. If the annotation already has tags, the button is Edit tags.
3. Type a tag name and press Enter. ZotLit suggests tag names from the item's library. To remove a tag, select the cross on it.
4. Press Escape or select outside the popup. ZotLit saves the tags to Zotero.

An annotation card has the same tag button. On a card, the tags save when you select elsewhere, and the editor stays open for more changes. To close it, press Escape or select the tag button again.

Escape does not add a name that you typed but did not add with Enter. A comma is part of the tag name, because Zotero tag names can contain commas. You can also remove automatic tags, as in Zotero.

If Zotero does not save the tags, or editing stops while you edit them, the card and the popup keep your tags under Unsaved tags. Select Save tags to try again.

Adjust an annotation's position

You can move or resize image, ink, and text annotations, move note annotations, and move either end of a highlight or underline. Editing must be enabled. When it is not, a selected mark shows no handles and the keys below do nothing.

1. Select the annotation mark in the PDF. Handles appear on the mark.
2. Drag a handle, or drag the mark itself. The mark follows the pointer.
3. Release the pointer. ZotLit sends the new position to Zotero.

Press Escape during a drag to put the mark back without saving. A drag that ends where it started saves nothing. The popup hides during the drag and returns after it.

Handles for each annotation type

An image rectangle stays on its page and keeps at least 10 points on each side. A text box keeps at least 10 points of width, and its height follows its text after a side handle moves. When you release a side handle on a box of one line, the box fits the width of its text. On a rotated text box, the handles rotate with the box. A highlight or underline range keeps at least one character. Its start stays on the annotation's page, and its end can move onto the next page but no further. A drag on the body of a highlight selects text as usual.

Adjust from the keyboard

Select the annotation mark first. Each key press is one step.

For a highlight or underline, add Ctrl (Windows) or Command (macOS) to the Shift keys to move the start instead of the end. A key that would leave the range with no characters does nothing. The Shift keys for images and text work as in Zotero's reader, with one difference: Shift+Up arrow does not make a text box narrower than 10 points. To move a mark, Zotero's reader uses an arrow key without a modifier. ZotLit uses Alt+arrow or Option+arrow.

Alt+arrow or Option+arrow does not move a mark that is within 10 points of the page edge on that side. Up arrow and Down arrow without a modifier still select the previous or next annotation in reading order.

How the change saves

Each drag release and each key press is one change. ZotLit sends it to Zotero at once. ZotLit also updates the annotation's place in the annotation list order, and for a highlight or underline, its quoted text. Zotero's reader and sidebar show the new position, and the image in the annotation view refreshes. To put the mark back where it was, see Undo and redo a change.

If the annotation changed in Zotero while you adjusted it, the annotation card shows Changed in Zotero and says that the position changed in Zotero. For a highlight or underline, the card also shows the Zotero quote beside yours. Select Apply again to save your position over the Zotero one, or Discard to keep the Zotero position. Until you select one, the mark shows the Zotero position.

If Zotero refuses the change, the mark returns to its saved position, and a notice says that the annotation was not adjusted and why.

Delete an annotation

1. Reveal the annotation in the annotation view.
2. Open its More options menu.
3. Select Delete annotation.
4. In the confirmation dialog, select Delete.

The annotation is deleted from Zotero. You can undo the deletion while the PDF is still open in Obsidian, but the restored annotation comes back under a new Zotero key. See Undo and redo a change.

To delete several annotations at once, select their cards in the annotation view. Then press Delete or Backspace, or open the More options menu of one of the selected cards and select the delete entry, for example Delete 3 annotations. After you confirm, one undo restores the whole group. See Use the annotation view for how to select several cards.

Undo and redo a change

While a PDF is open in Obsidian, ZotLit remembers the annotation changes it saved to Zotero for that PDF: creations, deletions, colors, comments, tags, quoted text, and positions. Undo asks Zotero for the previous value, and redo asks for the change again. Both are ordinary edits, so Zotero must be running and editing must be enabled.

The keys work anywhere in the PDF view, and in the annotation view on a card you selected, as long as the PDF is open. Inside a comment editor or a text box you are typing in, the same keys undo your typing instead. A held key steps once.

The command palette carries ZotLit: Undo annotation change and ZotLit: Redo annotation change. Neither has a shortcut of its own, so you can assign one. The PDF view's More options menu carries the same two entries, shown dimmed when there is nothing to step that way.

What counts as one step

Each creation, deletion, color change, and drag is one step. A deletion or color change on several selected cards is also one step. One ink stroke is one step, even where ZotLit saved a long stroke as more than one annotation.

Each save of tags is one step. Undo removes the tags that the save added and restores the tags that it removed. Tags that changed in Zotero since then stay as they are. One quoted-text editing session is also one step.

The comment text you save on one annotation is also one step, however many times it saved while you typed, and undo takes it back to the comment you started from. A change to anything else ends that step, and so does a change to that comment in Zotero, so the next comment you type on the same annotation starts a new one. A comment you leave as you found it records no step.

A run of keyboard nudges on one mark is one step while the presses are less than half a second apart. A pause longer than that, or a change of any other kind, starts a new step.

What the history covers

The history belongs to the PDF, not to the window. Two views of the same PDF, and the annotation view beside them, share one history in the order you made the changes. A change to another PDF is never in it.

ZotLit records a change only while a view of that PDF is open, and the history ends when you close the last one. Reopening the PDF starts an empty history, so an earlier session can never revert today's work. Refreshing the data, reloading the annotations, and changes made in Zotero all leave the history standing. A new change after an undo discards the steps you could have redone. The history holds the last 100 steps and is never written to disk.

After each step, the PDF view selects the annotation that changed and scrolls to it. When the step removed an annotation, the view clears the selection and returns to the page the annotation was on.

When undo stops

Before it writes, ZotLit checks that Zotero still holds what your change left there. If that annotation changed in Zotero since — by hand, by sync, or from another device — ZotLit writes nothing, drops that step, and shows This annotation changed in Zotero, so ZotLit left it as it is.. Press undo again to try the step before it. A Zotero change to a different field of the same annotation does not stop the undo, and neither does a Zotero value that already equals the one the undo would write.

Undo and redo do nothing while a change is still saving, or while you have unsaved comment text on an annotation the step would change. When editing is not enabled, they show the same notice as any other blocked edit.

A restored annotation gets a new key

Zotero cannot bring a deleted annotation back under its old key. When you undo a deletion, or redo a creation you undid, Zotero creates the annotation again with its color, comment, text, and position, but under a new Zotero key.

Links in your notes, excerpt images, and obsidian:// URIs that name the old key no longer resolve. ZotLit shows no notice for this. Pull the restored annotation into the note again, or update the key by hand.

See also