# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://alix-lahuec.gitbook.io/zotero-roam/v0.6/customization/other/notes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.