Formatting annotations

The extension has a built-in, template-based system for customizing how Zotero 6 annotations are imported into Roam. Two templates are available in user settings:

• Comment template: this is used to format Zotero annotations' comments

• Highlight template: this is used to format Zotero annotations' highlights

If you want more control over the output, you can also use a custom JavaScript function to format annotations.

Comment template

Replacements available:

• {{comment}} - the text of the comment

Defaults

{{! Template }}
{{comment}}

{{! Output }}
Find literature on the relationship between [[health literacy]] and the use of virtual visits and [[telemedicine]]

Highlight template

Replacements available:

• {{highlight}} - the highlighted text

• {{link_page}} - the address of the link to the highlight's page in the PDF, e.g zotero://open-pdf/library/items/ABCD123?page=25

• {{page_label}} - the annotations' page, from the PDF file. For example, if a paper was published in a journal on pages 532-539, the first page is labelled532.

• {{tags_string}} - the comma-separated list of tags associated with the annotation, e.g #[[TODO]], #[[Important]]

Defaults

{{! Template }}
[[>]] {{highlight}} ([p. {{page_label}}]({{link_page}})) {{tags_string}}

{{! Output }}
[[>]] Lorem ipsum sed elit ([p. 3](zotero://open-pdf/library/items/ABCD123?page=25)) #[[TODO]], #[[Important]]

Using a JavaScript function

Specifications

The function takes a single argument, the Array of annotations for the item. In your user settings, you can choose to receive the annotations as:

• Raw metadata

• Simplified metadata

See below for more details.

Return Value

The function must return an ordered Array, containing the blocks to be added to Roam.

Blocks can be provided in two forms:

• A simple string of text, which will create a childless block

• An Object with a string property, and an optional children property: { string: "The block's contents", children: [...] }

Getting Started

To get started with writing custom formatting functions for annotations, feel free to make use of this interactive Observable notebook.

zoteroRoam : Annotations formatting 🛠Observable

Sample data

Raw metadata

{
    data: {
        annotationColor: "#5fb236",
        annotationComment: "Find literature on the relationship between [[health literacy]] and the use of virtual visits and [[telemedicine]]",
        annotationPageLabel: "25",
        annotationPosition: "{\"pageIndex\":24,\"rects\":[[203.6,431.053,546.865,441.6],[203.6,419.056,536.829,429.603],[203.6,407.059,566.448,417.606],[203.6,395.062,564.521,405.609],[203.6,383.065,265.699,393.612]]}",
        annotationSortIndex: "00024|001317|00350",
        annotationText: "Digital health literacy may also have an impact on the use of digital health services such as virtual visits. This was indicated in the results of Canadian surveys of digital health experiences during the COVID-19 pandemic, which found that those with higher digital health literacy were more likely to use digital health services compared with those with lower digital health literacy.",
        annotationType: "highlight",
        dateAdded: "2022-03-18T13:00:00Z",
        dateModified: "2022-04-02T12:00:00Z",
        itemType: "annotation",
        key: "H65PKESD",
        parentItem: "ABCD123",
        relations: {},
        tags: [{ tag: "Important" }, { tag: "TODO" }],
        version: 4557
    },
    key: "H65PKESD",
    library: {type: 'user', id: 123456, name: 'username', links: {…}}, // Metadata about the library
    links: {self: {…}, alternate: {…}, up: {…}}, // Links to the annotation and its parent
    meta: {},
    version: 4557
}

Simplified metadata

{
	color: "#5fb236",
	comment: "Find literature on the relationship between [[health literacy]] and the use of virtual visits and [[telemedicine]]",
	date_added: "2022-03-18T13:00:00Z",
	date_modified: "2022-04-02T12:00:00Z",
	day_added: "March 18th, 2022",
	day_modified: "April 2nd, 2022",
	key: "H65PKESD",
	library: "users/123456",
	link_pdf: "zotero://open-pdf/library/items/ABCD123",
	link_page: "zotero://open-pdf/library/items/ABCD123?page=25",
	page_label: "25",
	parent_item: "ABCD123",
	position: {
		pageIndex: 24,
		rects: [
			[203.6,431.053,546.865,441.6],
			[203.6,419.056,536.829,429.603],
			[203.6,407.059,566.448,417.606],
			[203.6,395.062,564.521,405.609],
			[203.6,383.065,265.699,393.612]
		]
	},
	raw: {...}, // The raw metadata for the annotation
	sortIndex: [24,1317,350],
	tags: ["Important", "TODO"],
	tags_string: "#[[Important]], #[[TODO]]",
	text: "Digital health literacy may also have an impact on the use of digital health services such as virtual visits. This was indicated in the results of Canadian surveys of digital health experiences during the COVID-19 pandemic, which found that those with higher digital health literacy were more likely to use digital health services compared with those with lower digital health literacy.",
	type: "highlight"
}