Roam Research Bulk Block Reference Updater

WHAT IT DOES

Roam Research Bulk Block Reference Updater is a productivity tool that streamlines the process of updating block references and page references across a Roam Research graph. Instead of manually searching through notes, finding each reference occurrence, and replacing it one by one—a process that can be tedious and error-prone—this script automates the detection phase. It scans the current page for Roam Research-style references including block references ((ref)) and page references [page], identifies all unique references with their occurrence counts and context snippets, and presents them as a scrollable checklist. You can select individual references, use Select All/Deselect All toggles, enter a new reference name, and generate comprehensive find/replace instructions that you can apply in your code editor or Roam Research's import/export workflow. The script supports dry run mode (preview only) and includes options for case sensitivity. This is ideal for Roam Research users who want to maintain consistent naming across their knowledge graph without spending hours on manual updates.

WHERE IT RUNS

This script is universal—it runs on any website (*://*/*) as a userscript injected through the BotGentz extension. It operates within the context of your current browser tab and cannot access other tabs, bookmarks, history, or downloads. The script reads the page DOM to identify Roam Research-style references using regex patterns ((ref)) and [page], extracts occurrence counts and contexts, and generates replacement instructions. All operations occur locally in your browser; no data is sent to external servers. The script outputs find/replace instructions to your clipboard for manual application in Roam Research.

HOW TO USE

1. Open any page containing Roam Research-style markdown notes (exported JSON, HTML, or text).

2. Click the BotGentz extension icon and select "Roam Research Bulk Block Reference Updater" from the script list.

3. The panel opens on the right side of the page. It automatically scans the current page for references.

4. Review the detected references, showing each reference, occurrence count, and a context preview.

5. Enter the new reference name in the "Rename to" field (e.g., ((new-ref)) or [New Page]).

6. Toggle "Dry run (preview only)" to preview changes without generating apply instructions.

7. Toggle "Case sensitive" to control whether reference matching is case-sensitive.

8. Toggle "Include children references" to include nested references.

9. Check the boxes next to references you wish to update. Use "Select All" or "Deselect All" for quick selection.

10. Click "Generate Replacement" to copy find/replace instructions to your clipboard.

11. Apply the find/replace patterns in your editor or during Roam export/import.

WHY IT WORKS WHERE OTHERS FAIL

Many Roam Research automation tools require the Roam app to be running and have limited batch capabilities. This script takes a different approach: it works on any page containing Roam-style reference text—including exported files, pastebin notes, or web-based viewers—making it useful even when Roam isn't open. It uses regex-based reference detection that handles both block references ((ref)) and page references [page], the two most common reference types in Roam Research. The script's output is designed for practical use: it generates clear find/replace patterns with properly escaped special characters, and includes context information so you can verify changes before applying. By focusing on generating replacement instructions rather than directly modifying files, it gives you full control over the renaming process while eliminating the manual effort of identifying reference locations.

THE PANEL

The script uses BotGentz's BGPanel system, which provides a floating, draggable panel on the right side of your screen. Drag the panel by its header to reposition it anywhere on the page—the panel remembers its position per site and snaps to the nearest edge when released. Click the minimize button to collapse the panel to a small floating bubble; click the bubble to expand it back. Resize the panel vertically by dragging its bottom edge. Press the Escape key to close the panel entirely. All panel state (position, collapsed/expanded) is persisted locally using GM_setValue, so your preferences survive page reloads.

PLEASE NOTE

This userscript requires the free BotGentz browser extension—it is not a standalone application. The script detects references on the current page and generates find/replace instructions—it does not automatically modify your Roam Research graph. You will need to use an editor with find/replace functionality or apply the changes during Roam export/import. This script does not store, transmit, or process any of your data outside your local browser. It does not access your password, hidden inputs, or file inputs. Use responsibly and always review find/replace patterns before applying them to your Roam Research graph.