notes

The notes setting lets you customize how Zotero notes are processed for Roam import

Settings

Name	Default value	Description
use	'text'	The type of input that should be received by the formatting function. Should be either : 'text' (default) : an Array of Arrays, where each child Array contains the HTML text of all notes - split into blocks based on split_char 'raw' : an Array of objects, where each object contains all the raw data for a note item, as received by the Zotero API
split_char	'\n'	The character(s) to use to split a note item into Roam blocks. This is only used if use is 'text'.
func	'zoteroRoam.utils.formatItemNotes'	The name of the function to be used to parse notes for import into Roam. This should be defined in conjunction with use: if you're writing a function that parses the HTML content, set use: 'text' if you're writing a function that makes use of the raw Zotero data for each note, set use: 'raw'.

Default behavior

By default, the extension will call the built-in parser function zoteroRoam.utils.formatItemNotes(...), give it as input a nested Array structure (use: 'text') where each string element will be a Roam block (elements obtained by splitting the note on split_char: '\n'). This replicates the default behavior of v0.5.

However, if you are using the zoteroRoam.formatting.getChildren utility in your custom metadata formatting function, know that it will now use the settings above to format your notes - instead of always using the extension's built-in. So, if you change these settings, the output will be modified accordingly without you having to rewrite your function's code 🎉

Examples

Changing how Roam blocks are delimited

Simply change split_char to be whatever character you'd like.

// Splitting notes into blocks based on paragraph tags
zoteroRoam_settings = {
    // dataRequests: {...}, (the usual contents of your settings object)
    notes: {
        split_char: "</p>"
    }
}

Using a custom parser function

Write your function, with the syntax window.myParser = function(notes){...}, and supply its name as the value for the func argument. Set the use parameter as needed :

Setup

// Assuming you've declared your function somewhere
// window.myParser = function(notes){...}


// If you're writing a parser that uses the raw data :
zoteroRoam_settings = {
    // dataRequests: {...}, (the usual contents of your settings object)
    notes: {
        use: "raw",
        func: "myParser"
    }
}

// If you're writing a parser that cleans up the HTML only,
// and want to keep the default split_char :
zoteroRoam_settings = {
    // dataRequests: {...}, (the usual contents of your settings object)
    notes: {
        func: "myParser"
    }
}

Example of a custom parser

// The below function does the following :
// 1- flattens the nested Array structure
// (i.e, does not care if there is one note or several)
// 2- parses each block to detect if it contains "highlight-red"
// (if it does, an #important tag is added to the block)
// 3- runs each block through the built-in utility to clean the HTML markup,
// and returns the result to be imported into Roam

window.myParser = function(notes){
  // Step 1
  let blocks = notes.flat(1);
  // Step 2
  blocks = blocks.map(b => {
    return b.includes("highlight-red") ? (b + " #important") : b;
  });
  // Step 3
  return blocks.map(b => zoteroRoam.utils.parseNoteBlock(b)).filter(b => b.trim());
}

If you decide to write your own parsing function, know that you'll have to clean all the HTML markup yourself. You can use the utility function zoteroRoam.utils.parseNoteBlock(item){...} which accepts a block (a string) as input, and returns its cleaned version.