Polar is a personal knowledge repository for PDF and web content supporting incremental reading and document annotation.

repo name	burtonator/polar-bookshelf
repo link	https://github.com/burtonator/polar-bookshelf
homepage	https://getpolarized.io/
language	TypeScript
size (curr.)	55892 kB
stars (curr.)	3630
created	2018-05-28
license	GNU General Public License v3.0

Polar is personal knowledge repository which supports advanced features like incremental reading, annotation, comments, and spaced repetition. It supports reading PDF and the web content and was created using the Electron framework and PDF.js

Features

• PDF support We have first-class PDF support thanks to PDF.js. PDFs work well when reading content in book format or when reading scientific research which is often stored as PDF.

• Captured Web Pages Download HTML content and save them as offline documents which can be annotated.

• Pagemarks Easily keep track of what you’re reading and the progress of each document.

• Text Highlights Highlight text in PDF and web pages.

• Area Highlights Capture a region of the page as a highlight which can be a chart, figure, infographic, etc.

• Local Storage All content is stored locally.

• Hackable The entire system is based on Electron, Node, pdf.js, React and other web standards. If you’re a developer - welcome home!

• Standards Based All content is stored as JSON in a well documented schema. Annotations never mutate the original content.

• Portable Run across any platform. Linux, MacOS, and Windows supported. We also product snaps which means you can install our .deb files on Ubuntu or Debian but also any Linux distribution that supports snaps!

We hit 1.0 in 2018, and Polar’s mature enough to be nearing—or already—best-in-class for PDF and (especially) web annotations.

Screenshots

Downloads

Packages for Windows, MacOS, and Linux are available on the downloads page.

We also have a CHANGELOG available if you’re interested into what went into each release.

Discussion

We have both a Discord group and Reddit group if you want to discuss Polar.

If it’s a very technical issue it might be best to create a Github Issue.

Personal Knowledge Repository

Polar is a document manager for PDF and web content as well as a personal knowledge repository.

Polar allows you to keep all important reading material in one place including annotations and flashcards for spaced repetition.

It supports for features like pagemarks, text highlights, and progress tracking by keeping track of how much you’ve read including restoring pagemarks when you re-open documents.

Pagemarks are a new concept for tracking your reading inspired from incremental reading. They allow suspend and resume of reading for weeks and months in the future until you’re ready to resume, without losing your place.

Since you can create multiple pagemarks they work even if you jump around in a book (which is often in technical or research work).

Web Content

PDF is an excellent document format but we’ve found that many HTML pages don’t convert to PDF well since they were not intended to be printed.

Captured pages contain HTML content stored in phz (Polar HTML zip) files.

We fetch all resources, render the page as DOM and apply CSS, then de-activate the page by removing all scripts.

We then store the content in the phz archive format and serve the content directly to Electron.

This means you have long term storage for all your content. You can annotate it and use pagemarks without risk of the content changing.

To capture a new page just select File | Capture Web Page then enter a URL.

After that the page will be captured and then loaded.

Local Storage

All annotations, documents, PHZ files and other data are persisted on disk in your ~/.polar directory (different on each platform) and when you re-open a PDF or PHZ file your pagemarks and other annotations are restored.

Since storage is local you’re not reliant on one specific cloud provider. You can also use tools like git or Dropbox to synchronize across machines.

Text Highlights

Text highlights allow you to work with content like you’re using a text highlighter in a book.

Create a text highlight.

Select text you want to highlight then hit Ctrl-Alt-T

Delete a text highlight.

Right click the highlight and select delete.

Key bindings:

• Ctrl-Alt-T - create a new text highlight from the current selected text.

Area Highlights

Area highlights allow you highlight a figure, infographic, or anything visual in a document.

Create an area highlight.

Right click on a page and select “Create area highlight”

Delete an highlight.

Right click the highlight and select delete.

Flashcards

Flashcards allow you to retain information long term by using a spaced repetition system like Anki to continually re-train yourself on material you want to retain.

Flashcards can be created by right clicking an annotation and selecting “Create Flashcard”. The resulting flashcards are stored as annotations in your repository.

To specify the Anki deck for a document, add a tag starting with deck:. Slashes are used to specify subdecks. For instance, to set a document to the Anki deck ML::100PageMLBook, use the Polar tag deck:ML/100PageMLBook.

Hackable

Since the entire platform is based on Electron (Node + Chromium) the platform is very easy to work with which means developers can contribute easily.

Feel free to fork and send a pull request if there’s some interesting feature you would like to add. Here is a list of good newcomer issues.

Data

All data is stored on disk in JSON format. This also includes extracted metadata from the document. For example, text highlights include the source text that you copied as well as pointers into the original document where they can be found.

Principles

We believe the following design principles are core to seeing this as a successful project.

• All the data should support long term file formats. The on disk format we use is JSON.

• Portability to all platforms is critical. We’re initially targeting Linux (Ubuntu), MacOS, and Windows. You shouldn’t have to pick a tool, which you might be using for the next 5-10 years, and then get stuck to a platform which may or may not exist in the future.

Build from source

Install NodeJS and npm for your platform.

To run:

Install latest stable node and npm versions.

You can check which version you need at

https://nodejs.org/

… then run:

$ git clone https://github.com/burtonator/polar-bookshelf
$ cd polar-bookshelf
$ npm install && npm run-script compile && npm start

Donations

Polar is supported by community donations

All donations go to supporting Polar which include website hosting costs, web designer costs, continual integration services, etc.

Contributors

This project exists thanks to all the people who contribute.

Backers

Thank you to all our backers! 🙏 [Become a backer]

Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]

License

Polar is distributed under the GPLv3.

PDF.js is available under the Apache License. Electron is released under the MIT License. Rest of the code is MIT-licensed.