Annotations v1.0.1

Hosted Version Source →

Newseful's annotation module provides a convenient syntax for adding contextual detail to a story without sacrificing brevity. A simple, easy-to-understand pattern creates inline-tooltips with supporting information or geographic data.


The annotations module is independent of external dependencies, so setting it up is quite simple. Just include this script tag anywhere on your site:

<script src=‘’></script>

You’ll also need a link to the Newseful style sheet, unless you plan on styling the timeline yourself. To include the Newseful style sheet, add this code to the head section of your page.

<link rel=‘stylesheet’ href=‘’>

Now you’ll need to tell the annotations module what the container element is for the article, and it will look there for instances of the syntax described below. Use this code to initialize the module:

var opts = {
	textElement : document.querySelector(‘YOUR SELECTOR‘)

var annotations = new NFAnnotations(opts);


The power of the annotation module is in its declarative syntax. To specify a contextual aside, a reporter need only adhere to the following syntax:

New York's (( name: Michael Bloomberg; title: Former Mayor, New York City; description: American business magnate, politician, and philanthropist. He served as the 108th Mayor of New York City, holding office for three consecutive terms beginning with his first election in 2001.; net worth: $35.5b )) declined to comment at press time.

This will generate a tooltip inline much like the one to the right.

The entire block of text specifying the annotation must be wrapped in ((double parentheses))

Within the parentheses, data must be split into keys and values. Newseful’s annotation module looks for certain keys to use for default layouts, but any text may be used as a key and will be formatted with the generic structured data layout. Keys must be separated from their values with a colon, and values must be terminated with a semicolon (as such they may not contain semicolons within them).

name: Michael Bloomberg;


The annotations module has several default keys that it looks for:

  • Name
  • Title
  • Description
  • Location*

The location key is special, and requires some additional setup, covered below.


Newseful’s annotation module also allows for the easy addition of contextual maps to a story, as seen to the right. However, in order to implement the maps feature, you will need to provide an API key for the Mapbox API

To initialize the annotations module with your Mapbox API key, use the following code:

var opts = {
	textElement : document.querySelector(‘YOUR SELECTOR’),
	apiKey : ‘YOUR API KEY’

var annotations = new NFAnnotations(opts);

The use of the your Mapbox API key will of course be subject to the terms of service laid out by Mapbox, so be sure that your plan can support the views you will receive.

Example Story

Originally published on

St. Louis County officials announced Monday night that a grand jury had declined to indict ((name: Ferguson, Mo.,; location: Ferguson, Missouri, US)) Police Officer ((name: Darren Wilson; title: Police Officer; description: Officer in the Ferguson, MO police department, shot Michael Brown in highly controversial series of events in Summer of 2014)) in the shooting of Michael Brown. Here’s what we know about the deadly encounter.

What’s the police version of events?

Wilson has not spoken publicly about what happened, and no direct video of the shooting has surfaced. According to a preliminary police account, which was included in Brown’s official ((name: autopsy report; description: Official report released by the St Louis coroner; date: 08/10/2014; pub: 11/2014)), the confrontation began when Wilson, on patrol, spotted Brown and a friend, Dorian Johnson, walking in the street.

Wilson “observed the two individuals, he requested that they get out of the roadway. The deceased became belligerent towards Officer Wilson,” the report stated. It continues:

Grand jury decides not to indict officer in Ferguson shooting Times staff writer Matt Pearce discusses a Missouri grand jury’s decision not to indict Ferguson police Officer Darren Wilson in the fatal shooting of Michael Brown. “As Officer Wilson attempted to exit out of his patrol vehicle the deceased pushed his door shut and began to struggle with Officer Wilson, during the struggle the Officer’s weapon was un-holstered. The weapon discharged during the struggle.

The deceased then ran down the roadway. Officer Wilson then began to chase the deceased. As he was giving chase to the deceased, the deceased turned around and ran towards officer Wilson.

Wilson then fired “several times,” the report said. (Police have not said exactly how many times Wilson fired his gun.) Official and private autopsies both appeared to show that Brown was shot at least six times during the encounter.

What does Brown’s friend say happened?

((name: Dorian Johnson; title: Friend of Michael Brown; description: Dorian Johnson was walking with Michael Brown on the day he was shot)) says that when the incident began, Wilson used profanity to tell the young men to get out of the street, hit Brown with his car door while trying to open it, then grabbed Brown by the neck.

“They’re not wrestling so much as his arm went from his throat to now clenched on his shirt,” Johnson told MSNBC. “It’s like tug of war. He’s trying to pull him in. He’s pulling away, that’s when I heard, ‘I’m gonna shoot you.’”

After the first shot wounded Brown, Johnson said, Brown ran and Wilson chased him. Wilson then shot Brown in the back, and Brown stopped, turned with his hands up, and said, “I don’t have a gun, stop shooting!” according to Johnson’s account to MSNBC.

As Wilson stood face-to-face with Brown, the officer shot him several more times, Johnson said.