Consider a procedure review that refers to one paragraph as “the cable inspection step.” The author changes its first sentence and moves the paragraph. A reference based only on the text or its current position can lose its target. A block ID gives the application a different handle, although the application still needs a policy for deleted, split, or merged targets.
Assign IDs to the blocks you actually reference
For an existing Tiptap installation with compatible packages:
import UniqueID from '@tiptap/extension-unique-id';
const procedureBlockIds = UniqueID.configure({
types: ['heading', 'paragraph'],
attributeName: 'uid'
});
Include procedureBlockIds once in the editor's extension list. Keep the schema's normal heading and paragraph support. The default types list is empty, so merely importing the extension is not enough to identify the blocks your application cares about.
Using types: 'all' includes every node type except doc and text. Choose that scope only if every included type has a purpose in the application's identity system. An ID on a paragraph should not silently become the identity of a person mentioned inside it. The mention guide covers that separate reference.
The default generator supplies unique values. If the application replaces it, use a generator appropriate for actual uniqueness. Avoid generating an ID from the paragraph's position or visible text: positions move, text changes, and identical paragraphs can legitimately coexist.
Inspect both stored JSON and exported HTML
The chosen configuration adds a uid attribute to supported nodes. An illustrative saved paragraph can look like this:
{
"type": "paragraph",
"attrs": { "uid": "step-example-1" },
"content": [
{ "type": "text", "text": "Inspect the cable jacket." }
]
}
step-example-1 is a readable fixture value, not the extension's claimed generated output. In HTML, inspect the paragraph's data-uid attribute. Save through the application's supported JSON or HTML path and confirm that any sanitizer, serializer, or import step preserves the intended attribute.
A data-uid value does not create an HTML id. Linking to #step-example-1 therefore needs a separate, deliberate rendering and anchor policy. The HTML anchor guide explains the browser mechanism. Do not promise direct section navigation merely because a model node has an identifier.
Define what a review reference does after structural edits
Use a disposable procedure with two paragraphs. Record their IDs, then change wording, split a paragraph, merge paragraphs, paste a copy, and undo. Inspect the actual IDs after each operation in the installed version. Confirm uniqueness across the configured nodes and that plain wording edits do not unexpectedly reset a surviving block's identity.
The extension manages node IDs, but it cannot decide where an external review comment belongs after its original paragraph becomes two paragraphs. Decide whether the application retains a reference to one surviving block, asks the reviewer to reattach it, or marks it unresolved. An ID also supplies no access permission to retrieve a document.
For a view that must not modify its loaded content, the current extension supports updateDocument: false. That prevents it from adding IDs to the document in that mode; it does not fill missing IDs in an immutable archive automatically. Existing records without IDs need a deliberate migration or normalization path.
Coordinate with shared-document initialization
When using Collaboration, the UniqueID documentation requires waiting for the collaboration provider to synchronize before mounting an editor that would mutate an empty shared document. It also documents filtering collaboration-origin transactions with isChangeOrigin. Follow the installed provider's initialization lifecycle rather than seeding the same initial content independently in each client.
The collaboration guide explains shared-document and fragment identity. Finish the procedure check by reopening the saved record and locating the inspection paragraph through its actual stored ID. Read its current wording beside the review reference so a surviving identifier is not mistaken for proof that the review still applies.