Extension defaults
A summary of the default parameters used by the extension to make API calls to Zotero, and format items in Roam.

About the limit parameter

In the Zotero API, the limit parameter is the maximum number of results to return. It must be an integer from 1-100 ; the default value is 25 items.
Within the extension, the limit parameter has a different meaning : it ends up determining the step size - i.e, the number of items that will be returned for each call made by the extension.
In the Zotero API
In the extension
A single request is made
A series of API requests are made
limit determines the maximum number of results to return for the request
limit determines the maximum number of results to return for each request
Number of results returned
The minimum between nbResults and limit
All results
The extension will make as many calls as necessary to obtain all the results that match the request, given the value of limit. In most cases, you'll want to use limit=100, to minimize the total number of requests that are made.
Since February 15th, all API calls beyond the initial request are made in parallel. This is done to improve performance for large datasets.

Item formatting in Roam

By default, the extension formats all items' data by calling the built-in getItemMetadata function. If you'd like to define item type-specific formatting, use your own formatting functions, and/or assign a different default formatting function, start with the funcmap documentation.


getItemMetadata is the extension's default formatting function, if the user hasn't defined any.
Function definition
Output structure
// This is taken directly from the extension's code file
zoteroRoam.formatting.getItemMetadata = function(item) {
let metadata = [];
if (item.data.title) { metadata.push(`Title:: ${item.data.title}`) }; // Title, if available
if (item.data.creators.length > 0) { metadata.push(`Author(s):: ${zoteroRoam.formatting.getCreators(item)}`) }; // Creators list, if available
if (item.data.abstractNote) { metadata.push(`Abstract:: ${item.data.abstractNote}`) }; // Abstract, if available
if (item.data.itemType) { metadata.push(`Type:: [[${zoteroRoam.formatting.getItemType(item)}]]`) }; // Item type, from typemap or zoteroRoam.typemap (fall back on the raw value)
metadata.push(`Publication:: ${ item.data.publicationTitle || item.data.bookTitle || "" }`)
if (item.data.url) { metadata.push(`URL : ${item.data.url}`) };
if (item.data.dateAdded) { metadata.push(`Date Added:: ${zoteroRoam.utils.makeDNP(item.data.dateAdded, {brackets: true})}`) }; // Date added, as Daily Notes Page reference
metadata.push(`Zotero links:: ${zoteroRoam.formatting.getLocalLink(item)}, ${zoteroRoam.formatting.getWebLink(item)}`); // Local + Web links to the item
if (item.data.tags.length > 0) { metadata.push(`Tags:: ${zoteroRoam.formatting.getTags(item)}`) }; // Tags, if any
let children = zoteroRoam.formatting.getItemChildren(item, {pdf_as: "links", notes_as: "formatted"});
metadata.push(`PDF links : ${children.pdfItems.join(", ")}`);
let notesBlock = {string: `[[Notes]]`, children: []};
return metadata;
getItemMetadata returns a flat array of String elements, which will be added as a series of top-level blocks to the item's Roam page :
  • Title::
  • Author(s)::
  • Abstract::
  • Type::
  • Publication::
  • URL :
  • Date Added::
  • Zotero links::
  • Tags::
  • PDF links :
  • [[Notes]]
It's a barebones structure, and is mostly meant to serve as backup function & starting point for users to create their own functions.


When using getItemMetadata to format an item's data, the extension creates a Roam block describing the item's type : Type:: [[<Item type>]]. By default, the <Item type> label will be determined through the extension's default mapping, which comes from the melat0nin/zotero-roam-export plugin :
zoteroRoam.typemap = {
artwork: "Illustration",
audioRecording: "Recording",
bill: "Legislation",
blogPost: "Blog post",
book: "Book",
bookSection: "Chapter",
"case": "Legal case",
computerProgram: "Data",
conferencePaper: "Conference paper",
document: "Document",
email: "Letter",
encyclopediaArticle: "Encyclopaedia article",
film: "Film",
forumPost: "Forum post",
hearing: "Hearing",
instantMessage: "Instant message",
interview: "Interview",
journalArticle: "Article",
letter: "Letter",
magazineArticle: "Magazine article",
manuscript: "Manuscript",
map: "Image",
newspaperArticle: "Newspaper article",
patent: "Patent",
podcast: "Podcast",
presentation: "Presentation",
radioBroadcast: "Radio broadcast",
report: "Report",
statute: "Legislation",
thesis: "Thesis",
tvBroadcast: "TV broadcast",
videoRecording: "Recording",
webpage: "Webpage"
If you'd like to define your own taxonomy of item types, start with the typemap documentation.