Annotator: a JavaScript library for adding annotation to webpages

What Annotator is for, and who it is actually for

Annotator is a JavaScript library for building annotation applications in browsers. It is not an annotation product you install and hand to end users. The README describes it as "a set of interoperable tools for annotating content in webpages", and the components it lists are the three things an annotation product needs and that a generic web app does not have: a user interface for creating, editing and displaying annotations; persistence components that save annotations to a remote server; and authorization and identity components that connect to your application's login and permissions system.

That framing tells you the audience. It is for developers who already have a web application, already have users and a backend, and want annotation as a feature inside it. The library takes a position on the browser side of the boundary. It does not ship a hosted service, and the README points at a demo page and a tagged release rather than a SaaS endpoint. If you want annotation as a finished product, this is the wrong layer of the stack.

The repository itself reflects the developer-library framing. Top-level entries include src/, test/, browser.js, index.js, a Makefile and a karma.conf.js. There is a demo.html and a dev.html, which is what you would expect from a library whose README tells you to open demo.html for a simple demonstration.

The mechanism: modules, a browserify bundle and an XPath range layer

The build is the clearest statement of how Annotator works. The Makefile defines the target pkg/annotator.js as a browserify run over browser.js, with -s annotator, which produces a standalone bundle exposing a global named annotator. The minified pkg/annotator.min.js is then produced by running uglifyjs over that bundle with a preamble generated by tools/preamble.

That means Annotator is consumed as a browser bundle, not as a server process. The package.json declares "browser": "browser.js" and a browserify transform, ./tools/cssify, so CSS shipped inside the source is pulled into the JavaScript bundle rather than being a separate stylesheet you must link. There is a css/ directory in the repository as well, so styles exist in both forms.

The dependency list is where the actual mechanism lives. jquery is a runtime dependency, and xpath-range at version 0.0.5 is what lets the library describe a selection in a page in a way that survives being stored and reloaded. backbone-extend-standalone supplies the class extension pattern, and es6-promise provides promises in environments that lack them. The locale/ directory suggests the interface strings are separated from the code.

The README is explicit that the library is extensible rather than fixed: it points to a module development page in the documentation, and the components are described as interoperable. So the intended shape is a small core plus modules you write for your own storage and identity backends. The README does not document the module interface itself; that lives in the external documentation site, which is a real gap if you are reading only the repository.

Installing Annotator and getting a first annotation on screen

The README gives two routes: read the Installing page in the documentation, or download a tagged release from the releases page and open demo.html. The repository's own development route is the npm one, and that is where the constraint appears.

Start by installing dependencies. The engines field in package.json pins node >=0.10 <0.12, so this step expects a Node 0.10 toolchain.

npm install

Once dependencies are present, the Makefile checks for browserify and fails early with a clear message if it is missing. The default target builds the library.

make

That writes pkg/annotator.js and pkg/annotator.min.js. The development server is wired to npm start, which the Makefile also exposes as make develop.

npm start

For a look at the library in use without building anything, open the bundled demo page from a downloaded release.

open demo.html

The README states that this gives a simple demonstration of the library. What it does not give you is a configured persistence backend: the README describes storage components as something that help you save annotations to a remote server, and the configuring page in the external documentation is where that is described. Expect the demo to show the interface, not a working multi-user deployment.

The release history is the main reason to hesitate

The most recent release listed is v2.0.0-alpha.3, dated 2015-07-03. Before it are v2.0.0-alpha.2 from 2015-04-25 and v1.2.10 from 2015-02-26. The package.json version matches the alpha, 2.0.0-alpha.3. So the newest published artefact is an alpha from 2015, and the newest stable release is v1.2.10 from earlier the same year.

The repository has not been archived, and the last push was on 2026-04-11. That combination is worth reading carefully. There is recent activity in the repository, but it has not produced a release in over a decade, and the version string still carries an alpha suffix. If your adoption criteria include a stable, recently published version, Annotator does not meet them. If your criteria are about the source being available and the interface being stable, the picture is different, but you should confirm that against the actual commits rather than the release list.

The toolchain pin reinforces the point. A package that requires Node 0.10 to build is not a package you drop into a current frontend pipeline without work. The devDependencies include karma 0.13, mocha 2.3 and phantomjs 1.9, all of which date from the same period. The presence of karma-chrome-launcher at ^3.2.0 is an exception, and suggests some dependency maintenance has happened, but the core test runner stack has not moved far.

The README also directs bug reports to the GitHub issue tracker and explicitly asks people not to use it for support questions, pointing instead at the annotator-dev mailing list. That is a normal open source arrangement, but it means the issue tracker is not a place to ask how to configure storage.

What Annotator does not do

The description says you can select text, images, or "(nearly) anything else". The parenthetical is doing real work. Annotation of arbitrary page content is a hard problem, and the xpath-range dependency at a pinned 0.0.5 is the component that carries the risk. If the page changes, or if the content is rendered by a framework that rewrites the DOM between page loads, a stored range can fail to resolve. The README does not document how the library handles a range that no longer matches, and the repository does not include a recovery strategy.

PDF annotation is outside the project's scope. The description is about webpages, the build produces a browser bundle, and the demo is an HTML page. If your requirement is marking up PDF files, this library is not the tool, and the popularity of PDF annotation searches around the word "annotator" does not change that.

There is also a licence question. The repository contains LICENSE, LICENSE-GPL and LICENSE-MIT files, and the package metadata records the licence as NOASSERTION. Two licence files with different terms is a signal that you need to read them yourself before shipping. The README and package.json do not resolve which terms apply to which parts, and I am not going to guess. Treat the dual licence files as a question for your own review, not as a settled fact.

Finally, the documentation is split. The README repeatedly defers to docs.annotatorjs.org for installing, configuring and module development. The repository contains a docs/ directory and a site/ directory, and the Makefile notes that public documentation is plain Markdown in ./site/docs while internal docs live in ./docs. If the hosted documentation site is unavailable, you are reading the repository copy.

How it compares with Hypothesis and with PDF markup tools

The closest alternative in spirit is Hypothesis, and the repository itself points in that direction. The README carries a Sauce Labs browser matrix under the name hypothesisannotator, and the IRC badge points at the #hypothes.is channel. Annotator is the library layer; Hypothesis is the service built around that idea, where the client, the storage and the identity are provided for you rather than assembled by you. The practical difference is who runs the backend. With Annotator you write the persistence and authorization components against your own systems, as the README's component list describes. With a hosted annotation service you accept someone else's storage and account model. If your annotations are meant to stay inside your application's permission model, that difference decides the choice.

For PDF work, the alternative is a dedicated PDF annotator, a different category of tool entirely. Annotator operates on the DOM of a webpage. A PDF viewer renders pages to canvas or to an embedded viewer, and the selection model is not the same. Moving between the two is not a configuration change.

There is a third comparison worth naming: writing the selection layer yourself. The reason to use Annotator rather than roll your own is the xpath-range dependency and the surrounding range handling, which is the part that is tedious to get right. The reason not to use it is everything around that: the 2015 release, the Node 0.10 pin, the Karma 0.13 test stack, and the split documentation. You are trading the range problem for a toolchain problem.

Maintenance, upgrades and what the licence files imply

The maintenance picture is mixed and should be stated plainly. The last push was on 2026-04-11, so the repository is not abandoned. The last release was v2.0.0-alpha.3 on 2015-07-03, so the published artefact is old. The version in package.json is still an alpha. Any upgrade path from v1.2.10 to v2.0.0-alpha.3 crosses a major version into an alpha, and no migration guide is included in the repository. CHANGES.md exists, so that is the first file to read before upgrading.

The build cost is a recurring one. Because the Makefile requires browserify and the engines field pins Node 0.10, building Annotator in a modern CI environment means either a container with that Node version or a fork that updates the toolchain. The Makefile's dependency tracking writes .deps/annotator.d, so incremental rebuilds after the first make are cheap. The clean target removes .deps and pkg.

On licensing, three files exist: LICENSE, LICENSE-GPL and LICENSE-MIT. The package metadata says NOASSERTION, which means npm could not determine a single licence from the package. GPL and MIT impose very different obligations on a distributed application. Read all three files against the parts of the project you intend to ship, and get your own advice if the answer matters to your distribution model. I can tell you the files are there; I cannot tell you which one governs your use.

Editorial conclusion

Adopt Annotator if you need to annotate arbitrary page content and are willing to pin an old Node toolchain, or if you are building on top of an existing Annotator deployment. Do not adopt it if you need a maintained, currently released library, or if you only need PDF markup, which this project does not cover. Before committing, run npm install under Node 0.10 and then npm test, because the engines field pins node >=0.10 <0.12 and the test script drives Karma in a single run.

Frequently asked questions

Official sources

1. Issues
2. openannotation/annotator on GitHub
3. Project website
4. README
5. Releases