@docs.plus/extension-hyperlink 1.5.2 → 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-2026 Hossein Marzban
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,454 +1,204 @@
-# Hyperlink
+# @docs.plus/extension-hyperlink
 
+<a href="https://docs.plus"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/docs-plus/docs.plus/main/apps/webapp/public/badges/badge-docsplus-dark.svg"><img alt="docs.plus" height="20" src="https://raw.githubusercontent.com/docs-plus/docs.plus/main/apps/webapp/public/badges/badge-docsplus.svg"></picture></a>
 [![Version](https://img.shields.io/npm/v/@docs.plus/extension-hyperlink.svg?label=version)](https://www.npmjs.com/package/@docs.plus/extension-hyperlink)
 [![Downloads](https://img.shields.io/npm/dm/@docs.plus/extension-hyperlink.svg)](https://npmcharts.com/compare/@docs.plus/extension-hyperlink)
 [![License](https://img.shields.io/npm/l/@docs.plus/extension-hyperlink.svg)](https://www.npmjs.com/package/@docs.plus/extension-hyperlink)
+[![Discord](https://img.shields.io/badge/discord-community-5865F2?logo=discord&logoColor=white)](https://discord.gg/2EmAjmgZ8)
 
-The Link extension adds support for `<a>` tags to the editor. The extension is headless, there is no actual <u>**UI**</u> to add, <u>modify</u> or <u>delete</u> links. The usage example below uses the native JavaScript prompt to show you how that could work.
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/docs-plus/docs.plus/main/extensions/extension-hyperlink/assets/demo-dark.gif">
+    <img alt="Typing "docs.plus" autolinks it, clicking the link opens a preview with copy, edit and remove, and Mod-K on a selected word opens the create-link form" width="640" src="https://raw.githubusercontent.com/docs-plus/docs.plus/main/extensions/extension-hyperlink/assets/demo-light.gif">
+  </picture>
+</p>
 
-In a real world application, you would probably add a more sophisticated user interface.
+Tiptap hyperlink mark with optional prebuilt popovers for creating, previewing, and editing links.
 
-## Installation
+It replaces the `@tiptap/extension-link` mark that StarterKit v3 bundles.
 
-````sh
-npm install @docs.plus/extension-hyperlink
-````
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/docs-plus/docs.plus/tree/main/extensions/extension-hyperlink/examples/vanilla?file=main.ts)
 
-## Settings
+## Why use it
 
-### protocols
+- **Autolink covers more than web URLs.** As you type, bare domains get `https://`, emails become `mailto:`, and E.164 phones become `tel:`. App schemes from a catalog of 47, such as `whatsapp://`, autolink too.
+- **The link UI is included.** Prebuilt create, preview, and edit popovers ship with the package. `Mod-k` opens the create-link form with no configuration. `@tiptap/extension-link` binds no keyboard shortcut.
+- **Every boundary checks the scheme.** `isSafeHref` blocks `javascript:`, `data:`, `vbscript:`, `file:`, and `blob:` on parse, import, write, serialize, and navigation. An embedded tab or newline cannot hide a scheme from the gate.
+- **Your `@tiptap/extension-link` configuration ports over.** `isAllowedUri` takes the same `(uri, ctx)` shape as `@tiptap/extension-link`, so an existing policy works unchanged. `setLink`, `unsetLink`, and `toggleLink` stay as aliases. `[label](url)` round-trips with `@tiptap/markdown`.
 
-Additional custom protocols you would like to be recognized as links.
+## Install
 
-Default: `[]`
+```sh
+npm install @docs.plus/extension-hyperlink
+```
 
-````js
-Hyperlink.configure({
-  protocols: ['ftp', 'mailto'],
-})
-````
+Or use `pnpm add @docs.plus/extension-hyperlink`, `yarn add @docs.plus/extension-hyperlink`, or `bun add @docs.plus/extension-hyperlink`.
 
-By default, [linkify](https://linkify.js.org/docs/) adds `//` to the end of a protocol however this behavior can be changed by passing `optionalSlashes` option
+Requires **`@tiptap/core` ^3.31.3** and **`@tiptap/pm` ^3.31.3** (Tiptap 3.x).
 
-````js
-Hyperlink.configure({
-  protocols: [
-    {
-      scheme: 'tel',
-      optionalSlashes: true
-    }
-  ]
-})
-````
+This package imports no React, Vue, or Next.js code. Use it from a plain page, Vite, React, Vue, Svelte, Next.js, Nuxt, or SvelteKit. Create the editor in the browser.
 
-### autolink
+React Native has no DOM. Load the editor in a web view.
 
-If enabled, it adds links as you type.
+Installs two runtime dependencies, `@floating-ui/dom` and `linkifyjs`. The popover engine and the tooltip ship inside `dist`, so they add no third package.
 
-Default: `true`
+Upgrading from `1.x`? Option names, command names, and CSS class names all changed — see [Migrating from 1.x](https://github.com/docs-plus/docs.plus/blob/main/extensions/extension-hyperlink/docs/migration.md#migrating-from-1x).
 
-````js
-Hyperlink.configure({
-  autolink: false,
-})
-````
+## Quickstart
 
-### openOnClick
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/docs-plus/docs.plus/tree/main/extensions/extension-hyperlink/examples/vanilla?file=main.ts)
 
-If enabled, links will be opened on click.
+Run this Quickstart in your browser first, with nothing to install. The app lives in [`examples/vanilla`](https://github.com/docs-plus/docs.plus/tree/main/extensions/extension-hyperlink/examples/vanilla).
 
-Default: `true`
+The host page needs one mount point: `<div id="editor"></div>`. The snippet also imports `@tiptap/starter-kit`. Add it with `npm install @tiptap/starter-kit` when your app has none yet.
 
-````js
-Hyperlink.configure({
-  openOnClick: false,
+```ts
+import { Editor } from '@tiptap/core'
+import StarterKit from '@tiptap/starter-kit'
+import {
+  Hyperlink,
+  createHyperlinkPopover,
+  editHyperlinkPopover,
+  previewHyperlinkPopover
+} from '@docs.plus/extension-hyperlink'
+import '@docs.plus/extension-hyperlink/styles.css'
+
+const editor = new Editor({
+  element: document.querySelector('#editor'),
+  content: '<p>Try <a href="https://example.com">this link</a>.</p>',
+  extensions: [
+    // Disable StarterKit's bundled link mark — see Caveats.
+    StarterKit.configure({ link: false }),
+    Hyperlink.configure({
+      popovers: {
+        previewHyperlink: previewHyperlinkPopover,
+        editHyperlink: editHyperlinkPopover,
+        createHyperlink: createHyperlinkPopover
+      }
+    })
+  ]
 })
-````
-
-### linkOnPaste
-
-Adds a link to the current selection if the pasted content only contains an url.
+```
 
-Default: `true`
+The `styles.css` import is optional. The snippet also styles no document link — see [Popovers](https://github.com/docs-plus/docs.plus/blob/main/extensions/extension-hyperlink/docs/popovers.md) and [Style document links](#style-document-links).
 
-````js
-Hyperlink.configure({
-  linkOnPaste: false,
-})
-````
+You should see a paragraph with one link. Click the link to open the preview popover, with copy, edit, and remove actions. Type `example.org` and a space, and the text becomes a link. Select a word and press `Mod-k` (Cmd on macOS, Ctrl elsewhere) to open the create-link form.
 
-### HTMLAttributes
+## Caveats
 
-Custom HTML attributes that should be added to the rendered HTML tag.
+- **`StarterKit.configure({ link: false })` is required, not stylistic.** StarterKit v3 bundles `@tiptap/extension-link` by default. The two marks collide on the `setLink` / `unsetLink` / `toggleLink` command names and on the `a[href]` parse rule. Your `extensions` array order then decides each contest, with no warning. If the upstream mark wins, this package's `isSafeHref` gate never runs on parsed or pasted HTML, and its popovers never attach.
+- **A click on a link needs `popovers.previewHyperlink`.** The three openers fall back to the prebuilt factory when a slot is `null`. The click handler does not: leave `previewHyperlink` at `null` and a click on a link opens no popover.
+- **`linkOnPaste: false` does not stop every paste from linking.** The linkify paste rule stays registered, so a pasted bare URL still becomes a link. To stop that path too, set `shouldAutoLink: () => false`, which every autolink path consults.
+- **`HTMLAttributes.target` reaches the DOM.** `HTMLAttributes: { target: '_blank' }` does emit `<a target="_blank">`. A browser-driven `target="_blank"` navigation skips the click gate. Leave `target` at `null` and let the click handler open the link.
 
-````js
-Hyperlink.configure({
-  HTMLAttributes: {
-    class: 'my-custom-class',
-  },
-})
-````
+The full list, with the reason for each, is in [Caveats](https://github.com/docs-plus/docs.plus/blob/main/extensions/extension-hyperlink/docs/api.md#caveats).
 
-### Modals
+## Common tasks
 
-The Modals configuration option lets you incorporate an interactive user interface similar to Google Docs for **setting** and **previewing** hyperlinks. This provides users with a more intuitive and interactive experience;
+### Set a link from your own button
 
-- [Dive into the code](https://github.com/HMarzban/extension-hyperlink/blob/4f37ffa18237f10d76c316844b1c2ab20b751fe9/packages/nextjs/src/components/Tiptap.tsx#L21-L28)
-- [Demo](https://github.com/HMarzban/extension-hyperlink#test-drive-with-our-demo-)
-
-<details>
-<summary>The `previewHyperlinkModal` function</summary>
+Every command lands on `editor.commands` and on `editor.chain()`. On `editor.commands`, each returns `boolean`, and `false` marks a no-op.
 
 ```ts
-function previewHyperlinkModal(options) {
-  const href = options.link.href;
-
-  const hyperlinkModal = document.createElement("div");
-  const removeButton = document.createElement("button");
-  const copyButton = document.createElement("button");
-
-  const newBubble = document.createElement("div");
-  newBubble.classList.add("hyperlink-preview-modal__metadata");
+editor.chain().focus().setHyperlink({ href: 'https://example.com' }).run()
+editor.getAttributes('hyperlink').href // read the current href
+```
 
-  const hrefTitle = document.createElement("a");
-  hrefTitle.setAttribute("target", "_blank");
-  hrefTitle.setAttribute("rel", "noreferrer");
-  hrefTitle.setAttribute("href", href);
-  hrefTitle.innerText = href;
+`setHyperlink` returns `false` when `href` is empty, when the [composed gate](https://github.com/docs-plus/docs.plus/blob/main/extensions/extension-hyperlink/docs/api.md#validate-vs-isalloweduri) rejects it, or when the schema cannot apply the mark there. See [Commands](https://github.com/docs-plus/docs.plus/blob/main/extensions/extension-hyperlink/docs/api.md#commands) for the full list.
 
-  newBubble.append(hrefTitle);
+### Open the create-link form
 
-  hyperlinkModal.classList.add("hyperlink-preview-modal");
+`Mod-k` calls this command. Call it from your own toolbar button too:
 
-  removeButton.classList.add("hyperlink-preview-modal__remove-button");
-  removeButton.innerHTML = "remove";
+```ts
+editor.commands.openCreateHyperlinkPopover()
+```
 
-  copyButton.classList.add("hyperlink-preview-modal__copy-button");
-  copyButton.innerHTML = "copy";
+`openCreateHyperlinkPopover` opens UI, so `editor.can().openCreateHyperlinkPopover()` reports availability without mounting anything. With nothing selected, the prebuilt form inserts the typed URL as its own link text.
 
-  removeButton.addEventListener("click", () => {
-    options.tippy.hide();
-    return options.editor.chain().focus().unsetHyperlink().run();
-  });
+### Style document links
 
-  copyButton.addEventListener("click", () => {
-    options.tippy.hide();
-    navigator.clipboard.writeText(href);
-  });
+The `styles.css` stylesheet skins the popovers only. The mark renders a plain `<a>` with no class, so style your document links yourself:
 
-  hyperlinkModal.append(newBubble, copyButton, removeButton);
+```ts
+Hyperlink.configure({ HTMLAttributes: { class: 'my-link' } })
+```
 
-  return hyperlinkModal;
+```css
+a.my-link {
+  color: #2563eb;
+  text-decoration: underline;
 }
-
 ```
 
-</details>
-
-<details>
-<summary>The `setHyperlinkModal` function</summary>
-
-```ts
-import { Editor } from "@tiptap/core";
-import { find } from "linkifyjs";
-
-let tooltip = undefined;
-
-function setHyperlinkModal(options) {
-  // Create the tooltip instance
-  if (!tooltip) tooltip = new options.Tooltip(options);
-
-  // Initialize the tooltip
-  let { tippyModal } = tooltip.init();
-
-  const hyperlinkModal = document.createElement("div");
-  const buttonsWrapper = document.createElement("div");
-  const inputsWrapper = document.createElement("div");
-
-  hyperlinkModal.classList.add("hyperlink-set-modal");
-
-  buttonsWrapper.classList.add("hyperlink-set-modal__buttons-wrapper");
-  inputsWrapper.classList.add("hyperlink-set-modal__inputs-wrapper");
-
-  // create a form that contain url input and a button for submit
-  const form = document.createElement("form");
-  const input = document.createElement("input");
-  const button = document.createElement("button");
-
-  input.setAttribute("type", "text");
-  input.setAttribute("placeholder", "https://example.com");
-  button.setAttribute("type", "submit");
-  button.innerText = "Submit";
-
-  inputsWrapper.append(input);
-  buttonsWrapper.append(button);
-  form.append(inputsWrapper, buttonsWrapper);
-
-  hyperlinkModal.append(form);
-
-  tippyModal.innerHTML = "";
-  tippyModal.append(hyperlinkModal);
-  tooltip.update(options.editor.view, {
-    arrow: options.roundArrow,
-  });
-
-  // make sure
-  setTimeout(() => input.focus();, 100);
-
-  // event listenr for submit button
-  form.addEventListener("submit", (event) => {
-    event.preventDefault();
-    const url = input.value;
+For theme tokens, dark mode, and class names, see [Styling](https://github.com/docs-plus/docs.plus/blob/main/extensions/extension-hyperlink/docs/styling.md).
 
-    if (!url) return;
+## Gallery
 
-    const sanitizeURL = find(url)
-      .filter((link) => link.isLink)
-      .filter((link) => {
-        if (options.validate) {
-          return options.validate(link.value);
-        }
-        return true;
-      })
-      .at(0);
+Prebuilt create, preview, and edit popovers (`styles.css` + `popovers` config). Each screenshot has a light and a dark version, and follows your system preference.
 
-    if (!sanitizeURL?.href) return;
-
-    tooltip?.hide();
+<details>
+<summary><strong>Create</strong> — Mod+K</summary>
 
-    return options.editor
-      .chain()
-      .setMark(options.extentionName, { href: sanitizeURL.href })
-      .setMeta("preventautohyperlink", true)
-      .run();
-  });
-}
-```
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/docs-plus/docs.plus/main/extensions/extension-hyperlink/assets/create-dark.png">
+    <img alt="Create-link popover with URL field and Apply button" width="640" src="https://raw.githubusercontent.com/docs-plus/docs.plus/main/extensions/extension-hyperlink/assets/create-light.png">
+  </picture>
+</p>
 
 </details>
 
 <details>
-<summary>The Hyperlink styles.scss</summary>
-
-```scss
-.tippy-box {
-  .hyperlink-preview-modal,
-  .hyperlink-set-modal,
-  .hyperlink-edit-modal {
-    background-color: #fff;
-    border-radius: 10px;
-    border: 1px solid #dadce0;
-    display: flex;
-    align-items: center;
-    justify-content: space-between;
-    padding: 6px 6px;
-    box-shadow: 0 1px 3px 1px rgba(60, 64, 67, 0.15);
-    margin-top: -6px;
-
-    &__metadata {
-      width: 200px;
-      display: flex;
-      align-items: center;
-      justify-content: flex-end;
-      flex-direction: row-reverse;
-      a {
-        font-size: 0.9rem;
-        margin-right: 6px;
-        white-space: nowrap;
-        overflow: hidden;
-        text-overflow: ellipsis;
-      }
-      img {
-        width: 18px;
-        height: 18px;
-        border-radius: 50%;
-        margin-right: 8px;
-      }
-    }
-
-    &__remove-button,
-    &__edit-button,
-    &__copy-button,
-    &__apply-button {
-      width: 30px;
-      height: 30px;
-      border-radius: 50%;
-      margin: 0 0.25rem;
-      display: flex;
-      align-items: center;
-      justify-content: center;
-      transition: background-color 0.1s ease-in-out;
-      &:hover {
-        background-color: #eee;
-      }
-      > svg {
-        width: 16px;
-        height: 16px;
-      }
-    }
-
-    form {
-      display: flex;
-      align-items: flex-end;
-      width: 100%;
-      input {
-        border: 1px solid #dadce0;
-        border-radius: 6px;
-        padding: 0.4rem 0.8rem;
-        margin-bottom: 0.2rem;
-        width: 100%;
-        &:last-of-type {
-          margin-bottom: 0;
-        }
-      }
-      .hyperlink-set-modal__buttons-wrapper,
-      .hyperlink-edit-modal__buttons-wrapper {
-        margin-left: 8px;
-        button {
-          border-radius: 6px;
-          padding: 4px 14px;
-          width: 70px;
-          margin-bottom: 0.2rem;
-          color: #1a73e8;
-          &:hover {
-            background: rgba(26, 115, 232, 0.04);
-            color: #174ea6;
-          }
-        }
-      }
-    }
-  }
+<summary><strong>Preview</strong> — click a link</summary>
 
-  .tippy-svg-arrow {
-    top: -6px !important;
-  }
-}
-```
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/docs-plus/docs.plus/main/extensions/extension-hyperlink/assets/preview-dark.png">
+    <img alt="Preview popover on a link — copy, edit, and remove actions" width="640" src="https://raw.githubusercontent.com/docs-plus/docs.plus/main/extensions/extension-hyperlink/assets/preview-light.png">
+  </picture>
+</p>
 
 </details>
 
-````ts
-import {
-  Hyperlink,
-  previewHyperlinkModal,
-  setHyperlinkModal
-} from "@docs.plus/extension-hyperlink";
-
-Hyperlink.configure({
-  modals: {
-    previewHyperlink: (data) => {
-      return previewHyperlinkModal(data);
-    },
-    setHyperlink: (data) => {
-      return setHyperlinkModal(data);
-    },
-  },
-})
-````
-
-> Note: The `previewHyperlinkModal` and `setHyperlinkModal` modals are prebuilt modal boxes. You can use them or create your own modal boxes. To learn how to create your own modal boxes, please check the [source code](https://github.com/HMarzban/extension-hyperlink/tree/main/packages/extension-hyperlink/src/modals)
-
-<Su>
-
-### Removing and overriding existing html attributes
-
-You can add `rel: null` to HTMLAttributes to remove the default `rel="noopener noreferrer nofollow"`. You can also override the default by using `rel: "your-value"`.
-
-This can also be used to change the `target` from the default value of `_blank`.
-
-````js
-Hyperlink.configure({
-  HTMLAttributes: {
-    // Change rel to different value
-    // Allow search engines to follow links(remove nofollow)
-    rel: 'noopener noreferrer',
-    // Remove target entirely so links open in current tab
-    target: null,
-  },
-})
-````
-
-### validate
-
-A function that validates every autolinked link. If it exists, it will be called with the link href as argument. If it returns `false`, the link will be removed.
-
-Can be used to set rules for example excluding or including certain domains, tlds, etc.
-
-````js
-// only autolink urls with a protocol
-Hyperlink.configure({
-  validate: href => /^https?:\/\//.test(href),
-})
-````
-
-## Commands
-
-### editHyperLinkText(), editHyperLinkHref(), editHyperlink()
-
-These commands allow you to edit the text and href value of a hyperlink.
-
-```js
-this.editor.commands.editHyperLinkText('New Text');
-this.editor.commands.editHyperLinkHref('https://new-url.com');
-this.editor.commands.editHyperlink({
-  newText: 'New Text',
-  newURL: 'https://new-url.com'
-});
-```
-
-### setHyperlink()
-
-Links the selected text.
-
-````js
-this.editor.commands.setHyperlink({
-  href: '<https://example.com>'
-});
-
-this.editor.commands.setHyperlink({
-  href: '<https://example.com>',
-  target: '_blank'
-});
-
-this.editor.commands.unsetHyperlink();
-````
-
-### unsetHyperlink()
-
-Removes a Hyperlink.
-
-````js
-this.editor.commands.unsetHyperlink();
-````
-
-## Keyboard shortcuts
+<details>
+<summary><strong>Edit</strong> — preview → Edit</summary>
 
-Doesn’t have a keyboard shortcut
-This extension doesn’t bind a specific keyboard shortcut. You would probably open your custom UI on `Mod-k` though.
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/docs-plus/docs.plus/main/extensions/extension-hyperlink/assets/edit-dark.png">
+    <img alt="Edit-link popover with URL and text fields and Apply button" width="640" src="https://raw.githubusercontent.com/docs-plus/docs.plus/main/extensions/extension-hyperlink/assets/edit-light.png">
+  </picture>
+</p>
 
-## Get the current value
+</details>
 
-Did you know that you can use `getAttributes` to find out which attributes, for example which href, is currently set? Don’t confuse it with a <u>command</u> (which changes the state), it’s just a method. Here is how that could look like:
+## Documentation
 
-```js
-this.editor.getAttributes('link').href
-```
+| Guide                                                                                                                   | What it covers                                                                                                          |
+| ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| [API reference](https://github.com/docs-plus/docs.plus/blob/main/extensions/extension-hyperlink/docs/api.md)            | Options, commands, keyboard shortcuts, the full caveats list, server bundles, and TypeScript exports                    |
+| [Popovers](https://github.com/docs-plus/docs.plus/blob/main/extensions/extension-hyperlink/docs/popovers.md)            | The three popover slots, factory option shapes, openers, and custom popovers                                            |
+| [Styling](https://github.com/docs-plus/docs.plus/blob/main/extensions/extension-hyperlink/docs/styling.md)              | The stylesheet, `--hl-*` theme tokens, dark mode, and class names                                                       |
+| [URL handling](https://github.com/docs-plus/docs.plus/blob/main/extensions/extension-hyperlink/docs/url-handling.md)    | Href normalization, scheme classification, and Markdown round-trip                                                      |
+| [Security](https://github.com/docs-plus/docs.plus/blob/main/extensions/extension-hyperlink/docs/security.md)            | The dangerous-scheme gate at each boundary, and the exported safety helpers                                             |
+| [Advanced](https://github.com/docs-plus/docs.plus/blob/main/extensions/extension-hyperlink/docs/advanced.md)            | The floating-popover primitive, the UI controller, and the tooltip primitive                                            |
+| [Migrating from 1.x](https://github.com/docs-plus/docs.plus/blob/main/extensions/extension-hyperlink/docs/migration.md) | Renamed options, commands, CSS classes, and popover APIs                                                                |
+| [Changelog](https://github.com/docs-plus/docs.plus/blob/main/extensions/extension-hyperlink/CHANGELOG.md)               | Every release and its breaking changes                                                                                  |
+| [For AI coding agents](https://cdn.jsdelivr.net/npm/@docs.plus/extension-hyperlink/README.md)                           | This README as plain Markdown for your agent. The docs are also on [Context7](https://context7.com/docs-plus/docs.plus) |
 
-## Sorce code and Example
+## Part of docs.plus
 
-- Demo:
-[extension-hyperlink](https://github.com/HMarzban/extension-hyperlink#test-drive-with-our-demo-)
-- Extension:
-[packages/extension-hyperlink](https://github.com/HMarzban/extension-hyperlink/tree/main/packages/extension-hyperlink)
-- Usage:  [packages/nextjs/src/components/Tiptap.tsx](https://github.com/HMarzban/extension-hyperlink/blob/59f45eba1886202f4840eb2112c34574c16fe68a/packages/nextjs/src/components/Tiptap.tsx#L19-L29)
+This extension is built for and maintained by [docs.plus](https://docs.plus). docs.plus is a free, real-time collaboration tool that lets communities organize knowledge hierarchically, with a chat thread on every heading. docs.plus runs these packages from source in production, so every release is exercised there before it reaches npm.
 
-## Inspiration and Acknowledgment, Let's Connect
+- Website: [docs.plus](https://docs.plus)
+- Project README: [docs-plus/docs.plus](https://github.com/docs-plus/docs.plus#readme)
+- Sibling extensions and recommended pairings: [extensions/README.md](https://github.com/docs-plus/docs.plus/blob/main/extensions/README.md)
 
-Thank you for exploring our Hyperlink extension from docs.plus! We aim to make collaboration and knowledge sharing not just easy, but also enjoyable.
+## Contributing
 
-Our extension is inspired by Tiptap's [extension-link](https://github.com/ueberdosis/tiptap/tree/main/packages/extension-link). While we've incorporated our own enhancements, we'd like to tip our hats to Tiptap for pioneering the "headless" approach that we admire greatly.
-> Please note: We're not affiliated with Tiptap, but we believe in recognizing foundational work.
+Bug reports and PRs welcome. Setup, test commands, and the playground harness live in [CONTRIBUTING.md](https://github.com/docs-plus/docs.plus/blob/main/extensions/extension-hyperlink/CONTRIBUTING.md).
 
-Your feedback and interest in docs.plus are invaluable to us. Share your thoughts, suggestions, or dive deeper into our mission at the [docs.plus](https://github.com/docs-plus/docs.plus) repository.
+## License
 
-Wish to converse? Connect with us [here](https://github.com/docs-plus/docs.plus#-connect-with-us).
+MIT — see [LICENSE](https://github.com/docs-plus/docs.plus/blob/main/LICENSE).