> For the complete documentation index, see [llms.txt](https://alix-lahuec.gitbook.io/zotero-roam/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alix-lahuec.gitbook.io/zotero-roam/v0.6/customization/other/notes.md).

# notes

### Settings

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

### 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.

```javascript
// 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 :

{% tabs %}
{% tab title="Setup" %}

```javascript
// 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"
    }
}
```

{% endtab %}

{% tab title="Example of a custom parser" %}

```javascript
// 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());
}

```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
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.
{% endhint %}