---
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. Internal bookmarks are partially preserved.

## What you need

- **Extensions:** `StarterKit` (includes the `Link` extension)
- **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](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 `<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.

```json
{
  "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`](https://tiptap.dev/docs/editor/extensions/marks/link.md) 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](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.

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.