--- title: "Hyperlinks and bookmarks" description: "How hyperlinks, email links, and internal bookmarks are handled across the DOCX conversion pipeline." canonical_url: "https://tiptap.dev/docs/conversion/content-types/structures-and-media/hyperlinks-bookmarks" --- # Hyperlinks and bookmarks How hyperlinks, email links, and internal bookmarks are handled across the DOCX conversion pipeline. 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](https://tiptap.dev/docs/conversion/import/docx/convertkit.md), which registers both the `Link` mark for hyperlinks and the `Bookmark` node for anchor targets. - **Configuration:** none required. ## Support overview | | Import | Editor | Export | | -------------------------------- | --------- | --------- | --------- | | External hyperlinks (http/https) | Supported | Supported | Supported | | Email links (mailto:) | Supported | Supported | Supported | | Internal anchor links | Supported | Supported | Supported | | Bookmark targets | Supported | Supported | Supported | | Inline formatting inside links | Supported | Supported | Supported | ## Import Import hyperlinks using the [editor extension](https://tiptap.dev/docs/conversion/import/docx/editor-extension.md) or the [REST API](https://tiptap.dev/docs/conversion/import/docx/rest-api.md). Both produce identical output. The conversion service detects `` elements and produces text nodes with a `link` mark. External links are resolved through the document's relationship file. ```json { "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: ```json { "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`: ```json { "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. > **Word's own bookmarks are imported too:** > > Word adds bookmarks of its own, such as `_GoBack` for the last edit position and `_Toc` entries behind a table of contents. These are imported like any other bookmark, so you may see `bookmark` nodes whose ids you did not create. They are zero-width and do not render anything, and they keep a generated table of contents working after a round-trip. > **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. ## Editor rendering ConvertKit registers the [`Link`](https://tiptap.dev/docs/editor/extensions/marks/link.md) extension, so no separate installation is needed. It renders link marks as `` 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 ``, so it takes no space and never clashes with the link's own `` element. Pass `bookmark: false` to ConvertKit to leave it out. ## Export Export hyperlinks using the [editor extension](https://tiptap.dev/docs/conversion/export/docx/editor-extension.md) or the [REST API](https://tiptap.dev/docs/conversion/export/docx/rest-api.md). 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.