Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/chrisgrieser/pdf-annotation-extractor-alfred

Alfred Workflow to extract annotations from PDF files.
https://github.com/chrisgrieser/pdf-annotation-extractor-alfred
alfred-workflow pandoc pdf pdf-annotation
Last synced: about 1 month ago
JSON representation
Alfred Workflow to extract annotations from PDF files.
Host: GitHub
URL: https://github.com/chrisgrieser/pdf-annotation-extractor-alfred
Owner: chrisgrieser
License: mit
Created: 2021-05-21T17:07:30.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2024-07-27T10:04:20.000Z (about 1 month ago)
Last Synced: 2024-07-27T18:22:38.069Z (about 1 month ago)
Topics: alfred-workflow, pandoc, pdf, pdf-annotation
Language: JavaScript
Homepage:
Size: 1.83 MB
Stars: 71
Watchers: 2
Forks: 5
Open Issues: 1
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Citation: CITATION.bib
Awesome Lists containing this project

README

        # PDF Annotation Extractor

![Download count](https://img.shields.io/github/downloads/chrisgrieser/pdf-annotation-extractor-alfred/total?label=Total%20Downloads&style=plastic)

![Last release](https://img.shields.io/github/v/release/chrisgrieser/pdf-annotation-extractor-alfred?label=Latest%20Release&style=plastic)

A [Workflow for Alfred](https://www.alfredapp.com/) to extract annotations as

Markdown file. Primarily for scientific papers, but can also be used for

non-academic PDF files.

Automatically determines correct page numbers, inserts them as Pandoc citations,

merges highlights across page breaks, prepends a YAML header with bibliographic

information, and more.

## Table of Contents

- [Installation](#installation)

- [Requirements for the PDF](#requirements-for-the-pdf)

	* [Automatic citekey identification](#automatic-citekey-identification)

- [Usage](#usage)

	* [Basics](#basics)

	* [Automatic Page Number Identification](#automatic-page-number-identification)

	* [Annotation Codes](#annotation-codes)

	* [Extracting Images](#extracting-images)

- [Troubleshooting](#troubleshooting)

- [Cite this software project](#cite-this-software-project)

- [Credits](#credits)

- [About the Developer](#about-the-developer)

## Installation

- Requirement: [Alfred 5](https://www.alfredapp.com/) with Powerpack

- Install [Homebrew](https://brew.sh/)

- Install `pdfannots2json` by running the following command into your terminal:

  `brew install mgmeyers/pdfannots2json/pdfannots2json`

- Download the [latest release](https://github.com/chrisgrieser/pdf-annotation-extractor-alfred/releases/latest/).

- Set the hotkey by double-clicking the sky-blue field at the top left.

- Set up the workflow configuration inside the app.

## Requirements for the PDF

`PDF Annotation Extractor` works on any PDF that has valid annotations

saved *in the PDF file*. Some PDF readers like **Skim** or **Zotero 6** do not

store annotations in the PDF itself by default.

This workflow automatically determines the citekey of based on the filename of

your PDF file.

- If the citekey is found, the `PDF Annotation Extractor`

prepends a yaml header to the annotations and [automatically

inserts the citekey](#automatic-page-number-identification) with the correct

page numbers using the [Pandoc citations

syntax](https://pandoc.org/MANUAL.html#citation-syntax).

- If your filename does not contain citekey that can be found in

  your library, the `PDF Annotation Extractor` extracts the annotations without

  a yaml header and uses the PDF numbers as page numbers.

### Automatic citekey identification

- The filename of the PDF file MUST begin with the citekey (without `@`).

- The citekey MUST NOT contain any underscores (`_`).

- The name of the file MAY be followed by an underscore and some

  text, such as `{citekey}_{title}.pdf`. It MUST NOT be followed by anything

  else, since then the citekey would not be found.

- Example: With the filename, `Grieser2023_Interdependent Technologies.pdf`, the

  identified citekey is `Grieser2023`.

> [!TIP]

> You can achieve such a filename pattern with automatic renaming rules of most

> reference managers, for example with the [ZotFile plugin for

> Zotero](http://zotfile.com/#renaming-rules) or the [AutoFile feature of

> BibDesk](https://bibdesk.sourceforge.io/manual/BibDeskHelp_77.html#SEC140).

## Usage

### Basics

Use the [hotkey](https://www.alfredapp.com/help/workflows/triggers/hotkey/) to

trigger the Annotation Extraction on the PDF file currently selected in Finder.

The hotkey also works when triggered from [PDF Expert](https://pdfexpert.com/)

or [Highlights](https://highlightsapp.net/). Alternatively, use the

`anno` keyword to search for PDFs and select one.

**Annotation Types extracted**

- Highlight ➡️ bullet point, quoting text and prepending the comment as bold text

- Free Comment ➡️ blockquote of the comment text

- Strikethrough ➡️ Markdown strikethrough

- Rectangle ➡️ [extracts image and inserts Markdown image link at the respective

  place](#extracting-images)

- Underlines ➡️ sent to `Reminders.app` as a task due today in the default list

### Automatic Page Number Identification

Instead of the PDF page numbers, this workflow retrieves information about the

*real* page numbers from the BibTeX library and inserts them. If there is no

page data in the BibTeX entry (for example, monographies), you are prompted to

enter the page number manually.

- In that case, enter the **real page number** of your **first PDF page**.

- In case there is content before the actual text (for example, a foreword or

  Table of Contents), the real page number `1` often occurs later in the PDF. If

  that is the case, you must enter a **negative page number**, reflecting the

  true page number the first PDF would have. *Example: Your PDF is a book, which

  has a foreword, and uses roman numbers for it; real page number 1 is PDF page

  number 12. If you continued the numbering backwards, the first PDF page would

  have page number `-10`, you enter the value `-10` when prompted for a page

  number.*

### Annotation Codes

Insert the following codes at the **beginning** of an annotation to invoke

special actions on that annotation. Annotation codes do not apply to

strikethroughs.

- `+`: Merge this highlight with the previous highlight or underline. Works for

  annotations on the same PDF-page (= skipping text in between) and for

  annotations across two pages.

  * `? foo` **(free comments)**: Turns "foo" into a Question

  Callout (`> ![QUESTION]`) and move up. (Callouts are [Obsidian-specific

  Syntax](https://help.obsidian.md/How+to/Use+callouts).)

- `##`: Turns highlighted text into a **heading** that is added at that

  location. The number of `#` determines the heading level. If the annotation is

  a free comment, the text following the `#` is used as heading instead. (The

  space after the is `#` required).

- `=`: Adds highlighted text as **tags** to the YAML frontmatter. If the

  annotation is a free comment, uses the text

  after the `=`. In both cases, the annotation is removed afterward.

- `_`: A copy of the annotation is sent `Reminders.app` as a task due today

  (default list).

> [!TIP]

> You can run the Alfred command `acode` to display a cheat sheet of all

> annotation codes.

### Extracting Images

- The respective images are saved in the `attachments` sub-folder of the output

  folder, and named `{citekey}_image{n}.png`.

- The images are embedded in the markdown file with the `![[ ]]` syntax, for

  example `![[filename.png|foobar]]`

- Any `rectangle` type annotation in the PDF is extracted as image.

- If the rectangle annotation has any comment, it is used as the alt-text for

  the image. (Note that some PDF readers like PDF Expert do not allow you to add

  a comment to rectangular annotations.)

## Troubleshooting

- Update to the latest version of `pdfannots2json` by running

  `brew upgrade pdfannots2json` in your terminal.

- This workflow does not work with annotations that are not actually saved in

  the PDF file. Some PDF Readers like **Skim** or **Zotero 6** do this, but you

  can [tell those PDF readers to save the notes in the actual

  PDF.](https://skim-app.sourceforge.io/manual/SkimHelp_45.html)

> [!NOTE]

> As a fallback, you can use `pdfannots` as extraction engine, as a different

> PDF engine sometimes fixes issues. This requires installing

> [pdfannots](https://github.com/mgmeyers/pdfannots2json/issues/11) via `pip3

> install pdfannots`, and switching the fallback engine in the settings. Note

> that `pdfannots` does not support image extraction and the extraction quality

> is slightly worse, so generally you want to use `pdfannots2json`.

## Cite this software project

If you want to mention this software project in an academic publication, please

cite it as:

```txt

Grieser, C. (2023). PDF Annotation Extractor [Computer software]. 

https://github.com/chrisgrieser/pdf-annotation-extractor-alfred

```

For other citation styles, use the following metadata:

- [Citation File Format](./CITATION.cff)

- [BibTeX](./CITATION.bib)

## Credits

- To [Andrew Baumann for pdfannots](https://github.com/0xabu/pdfannots), which

  caused me to develop this workflow (even though it does not use `pdfannots`

  anymore).

- Also, many thanks to [@mgmeyers for

  pdfannots2json](https://github.com/mgmeyers/pdfannots2json/), which enabled

  many improvements to this workflow.

- I also thank [@StPag](https://github.com/stefanopagliari/) for his ideas on

  annotation codes.

- Icons created by Freepik/Flaticon

## About the Developer

In my day job, I am a sociologist studying the social mechanisms underlying the

digital economy. For my PhD project, I investigate the governance of the app

economy and how software ecosystems manage the tension between innovation and

compatibility. If you are interested in this subject, feel free to get in touch.

- [Academic Website](https://chris-grieser.de/)

- [Discord](https://discordapp.com/users/462774483044794368/)

- [GitHub](https://github.com/chrisgrieser/)

- [Twitter](https://twitter.com/pseudo_meta)

- [ResearchGate](https://www.researchgate.net/profile/Christopher-Grieser)

- [LinkedIn](https://www.linkedin.com/in/christopher-grieser-ba693b17a/)