BookmarkNEW

Bookmark:

{
  name: string;
  anchor: BookmarkAnchor;
  rename(newName: string): Bookmark | undefined;
  remove(): boolean;
}

A named place in the document that links and page or text references can point at.

Remarks

A bookmark is identified by its name alone. A bookmark object is a snapshot, valid only inside the transaction that returned it; any other edit of the document can make its anchor stale. Keep its name to find the same bookmark again.

Its properties are read-only: assigning to them changes nothing in the document. Change a bookmark with Bookmark.rename and Bookmark.remove.

Page references, text references and links point at a bookmark by its name, and the two changes treat them differently: Bookmark.rename updates them to the new name, while Bookmark.remove does not touch them, so they keep the old name.

A bookmark cannot be moved in place: remove it and add it again with the same name, in the same transaction if needed. Page references, text references and links keep its name, so they point at the new place. See Bookmark.remove for an example.

Example

Read the text every bookmark marks:

for (const bookmark of draft.bookmarks().all()) {
  const text = bookmark.anchor.type === 'text' ? bookmark.anchor.ranges.map(({ text }) => text).join('\n') : '';
  console.log(bookmark.name, text);
}

Properties

name

readonly name: string

The bookmark’s name.

---

anchor

readonly anchor: BookmarkAnchor

Where the bookmark is: the text it marks, or its position.

Methods

rename()

rename(newName): Bookmark | undefined

Renames the bookmark, and updates every page reference, text reference and link that points at it to the new name, so they keep working.

Parameters

newName

string

A letter, then letters, digits or underscores, up to 40 characters, different from every other bookmark’s name in any case; it may differ from the current name in case only

Returns

Bookmark | undefined

The renamed bookmark, or undefined when the new name is invalid or taken, the bookmark no longer exists, or the participant may not rename it; the document is then unchanged

Remarks

Nothing else renames a bookmark safely: removing it and adding the new name leaves page references, text references and links on the old name, broken.

Bookmark changes are never tracked, so only an owner may rename one, and not in a review transaction. After a rename, this object refers to a name that no longer exists; use the returned bookmark instead.

Example

Rename a bookmark; the page references and links to it follow:

draft.bookmarks().get('Intro')?.rename('Chapter1');

---

remove()

remove(): boolean

Removes the bookmark and keeps its text. It does not change any page reference, text reference or link that points at it: they keep the removed name.

Returns

boolean

true when the bookmark was removed. Returns false, changing nothing, when it no longer exists or the participant may not remove it.

Remarks

Unless a bookmark with the same name is added again, those references are broken: once updated, a page reference shows “Error! Bookmark not defined.” and a text reference “Error! Reference source not found.”, and a link goes nowhere. To keep references working under a new name, use Bookmark.rename instead.

Deleting all of the bookmark’s text through a TextView removes it too, with the text; this method keeps the text.

Bookmark changes are never tracked, so only an owner may remove one, and not in a review transaction.

Examples

Remove a bookmark:

draft.bookmarks().get('Draft')?.remove();

Move a bookmark to the start of another paragraph; references and links to its name point at the new place:

const bookmark = draft.bookmarks().get('Intro');
const paragraph = draft.body().content().blocklevels()[2];

if (bookmark && paragraph?.type === 'paragraph') {
  bookmark.remove();
  draft.bookmarks().add({ name: 'Intro', anchor: { type: 'point', point: { textView: paragraph.asTextView(), placement: 'before' } } });
}