Hyperlinks and bookmarks

Hyperlinks convert between DOCX and Tiptap as link marks with an href attribute. External URLs and email links round-trip cleanly. Links that point somewhere else in the same document round-trip too, together with the bookmark targets they point at.

What you need

• Extensions: ConvertKit, which registers both the Link mark for hyperlinks and the Bookmark node for anchor targets.
• Configuration: none required.

Support overview

Import

Import hyperlinks using the editor extension or the REST API. Both produce identical output.

The conversion service detects <w:hyperlink> elements and produces text nodes with a link mark. External links are resolved through the document's relationship file.

{
  "type": "text",
  "text": "Visit the Tiptap website",
  "marks": [
    { "type": "link", "attrs": { "href": "https://tiptap.dev" } }
  ]
}

Links within the document

A link that jumps to another place in the same document, such as a table of contents entry or a "back to top" link, becomes a link mark whose href is a fragment:

{
  "type": "text",
  "text": "Go to introduction",
  "marks": [
    { "type": "link", "attrs": { "href": "#intro" } }
  ]
}

Word stores these links in more than one way, and all of them are imported:

• An anchor on the hyperlink element itself, which Word writes as w:anchor.
• A HYPERLINK field with the \l switch, in both its simple and its complex form.

When a link carries both a web address and an anchor, the two are combined into a single href, such as https://example.com#intro.

Bookmark targets

The place a link jumps to is a Word bookmark. Each one is imported as a zero-width bookmark node holding the bookmark's name as its id:

{ "type": "bookmark", "attrs": { "id": "intro" } }

The node sits at the position the bookmark started, so the anchor keeps its place in the document. A link points at it by using # followed by the same id. Bookmarks that sit between paragraphs rather than inside one are attached to the start of the following paragraph.

Editor rendering

ConvertKit registers the Link extension, so no separate installation is needed.

It renders link marks as <a> tags with the href attribute.

The extension adds target (default _blank) and rel (default noopener noreferrer nofollow) attributes automatically. These are not carried over from the DOCX import and are not included in the DOCX export.

Bookmark targets need the Bookmark node, which ConvertKit registers by default. Without it the anchors are dropped when the imported content is loaded into the editor, and links pointing at them stop resolving. The node is an inline atom that renders as an empty <span data-bookmark-id="...">, so it takes no space and never clashes with the link's own <a> element. Pass bookmark: false to ConvertKit to leave it out.

Export

Export hyperlinks using the editor extension or the REST API. Both handle links identically.

Links to a web address, including mailto: addresses, are wrapped in a DOCX external hyperlink with the Hyperlink style applied, and the href becomes an external relationship in the DOCX package.

A link whose href starts with # is exported as a Word internal hyperlink pointing at the matching bookmark, so it navigates inside the document just as it does in the editor. bookmark nodes are exported back into Word bookmarks, which is what those links point at.

A href of # on its own has no target to point at, so that text is exported without a link. A web address that merely contains a fragment, such as https://example.com#intro, is still an external link.

What round-trips

An external hyperlink with plain link text survives the full import, edit, export cycle. The href and visible text are preserved. The exported link uses the DOCX Hyperlink style (typically blue underlined text).

In-document navigation also survives the full cycle: a link keeps pointing at the same target, and the target keeps its position.

What changes: the target and rel attributes added by the editor are not carried into the DOCX.