Hyperlinks and bookmarks
Hyperlinks convert between DOCX and Tiptap as link marks with an href attribute. External URLs and email links round-trip cleanly. Internal bookmarks are partially preserved.
What you need
- Extensions:
StarterKit(includes theLinkextension) - Configuration: None required. External links work out of the box.
Support overview
| Import | Editor | Export | |
|---|---|---|---|
| External hyperlinks (http/https) | Supported | Supported (StarterKit) | Supported |
| Email links (mailto:) | Supported | Supported | Supported |
| Internal anchor links | Not supported (text preserved, link lost) | Not applicable (link not imported) | Exported as external hyperlink |
| Bookmark targets | Dropped | Not supported | Not supported |
| Inline formatting inside links | Supported | Supported | Supported |
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. Internal bookmark-style hyperlinks (which use w:anchor instead of r:id) are not imported. The text content is preserved but the link is not applied, because the importer only reads the r:id attribute.
{
"type": "text",
"text": "Visit the Tiptap website",
"marks": [
{ "type": "link", "attrs": { "href": "https://tiptap.dev" } }
]
}Inline formatting inside hyperlinks is preserved on import
When a DOCX hyperlink contains multiple runs with different formatting (for example, a bold word followed by a regular word), the importer iterates over each w:r independently. Per-run formatting such as bold and italic is preserved alongside the link mark.
Internal anchor links and bookmarks are not supported
Word bookmarks (<w:bookmarkStart> and <w:bookmarkEnd>) are not converted. Internal anchor hyperlinks (which use w:anchor instead of r:id) are also not imported. The text content is preserved, but the link is not applied because the importer only resolves relationships via r:id.
Editor rendering
The Link extension is included in StarterKit. 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.
Export
Export hyperlinks using the editor extension or the REST API. Both handle links identically.
The export converter wraps linked text in a DOCX ExternalHyperlink element with the Hyperlink style applied. The href becomes an external relationship in the DOCX package.
All links are exported as external hyperlinks, including mailto: addresses. Internal anchor references (#section-name) are exported as-is but will not function as internal navigation in Word because the export does not produce bookmark targets or InternalHyperlink elements.
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).
What changes: the target and rel attributes added by the editor are not carried into the DOCX.