Round-trip a declared attribute of the link mark through nodeToBlock/blockToNode, or open an InlineContentSpecs seam for link

[NodarDavituri]

The built-in link keeps only its href through BlockNote's block API, so a host application cannot store an author's choice about one link, such as whether it opens in a new tab, on the link itself. This asks for a way to do that. Every code link below is at v0.57.0, and the behavior was reproduced on @blocknote/core 0.57.0.

The gap

The link mark declares exactly one attribute, in link.ts, lines 91-100:

addAttributes() {
  return {
    href: {
      default: null,
      parseHTML(element) {
        return element.getAttribute("href");
      },
    },
  };
},

and the block API's Link type has type, href and content only. nodeToBlock.ts, lines 282-292 reads only href off the mark when it builds a link inline content item from a ProseMirror node, and so do lines 318-328 and lines 355-365:

currentContent = {
  type: "link",
  href: linkMark.attrs.href,
  content: [...],
};

and blockToNode.ts, lines 110-112 recreates the mark from href alone:

const linkMark = schema.marks.link.create({
  href: link.href,
});

as does editLink(), which the link toolbar's edit form calls, in StyleManager.ts, line 248.

target="_blank" and rel="noopener noreferrer nofollow" exist only as render-time HTMLAttributes defaults on the mark, in addOptions(), lines 77-89, and renderHTML() merges those options over the mark's own attributes. So every link an editor draws, and every link upstream's own toExternalHTML puts on the clipboard, already carries target="_blank", and nothing about that choice is ever stored or read back. A host application that wants an author-controlled per-link attribute, such as whether a link opens in a new tab, has no declared way to add one to link: unlike a custom type registered through InlineContentSpecs, the built-in link has no prop schema, and an attribute added to the mark from outside, through a TipTap extension's global attributes, reaches the ProseMirror schema but is dropped by both conversions, as step 3 below shows.

Steps to reproduce the gap

Seen on 2026-10-30 with @blocknote/core 0.57.0, @tiptap/core 3.32.2 and prosemirror-model 1.25.12, in a plain Vite page without React, in headless Chrome 156.0.8078.76. The comments under each console.log are what it printed.

1. Create an editor whose document has a link carrying two keys beside href, mount it, and read the document and the link mark back:

   import { BlockNoteEditor, createExtension } from "@blocknote/core";
   import { Extension } from "@tiptap/core";
   
   const doc = () => [
     {
       type: "paragraph",
       content: [
         {
           type: "link",
           href: "https://example.org/",
           target: "_blank",
           "data-kind": "internal",
           content: [{ type: "text", text: "x", styles: {} }],
         },
       ],
     },
   ];
   
   const linkMarkAttrs = (editor) => {
     const attrs = [];
     editor.prosemirrorState.doc.descendants((node) => {
       for (const mark of node.marks) {
         if (mark.type.name === "link") attrs.push(mark.attrs);
       }
     });
     return attrs;
   };
   
   const editor = BlockNoteEditor.create({ initialContent: doc() });
   editor.mount(document.getElementById("editor"));
   
   console.log(JSON.stringify(editor.document[0].content[0]));
   // {"type":"link","href":"https://example.org/","content":[{"type":"text","text":"x","styles":{}}]}
   console.log(JSON.stringify(linkMarkAttrs(editor)));
   // [{"href":"https://example.org/"}]
   console.log(document.querySelector("#editor a").outerHTML);
   // <a href="https://example.org/" target="_blank" rel="noopener noreferrer nofollow" classname="bn-inline-content-section" data-inline-content-type="link">x</a>

2. Load the same document into the running editor with editor.replaceBlocks(editor.document, doc()), and parse <p><a href="https://example.org/" target="_self" data-kind="internal">x</a></p> with editor.tryParseHTMLToBlocks().

Expected, if the link round-tripped an author-controlled attribute: the extra keys survive, and so do the HTML's target and data-kind. Actual, on 0.57.0: each time the link comes back as {"type":"link","href":"https://example.org/","content":[{"type":"text","text":"x","styles":{}}]}, the mark in the editor has the attributes {"href":"https://example.org/"} only, and nothing is logged. The keys are silently dropped the first time the document passes through the editor, whatever the input contained, and the rendered link, like the output of editor.blocksToHTMLLossy(), carries target="_blank" and rel="noopener noreferrer nofollow" regardless. links.HTMLAttributes does not change this: an editor created with links: { HTMLAttributes: { target: "_self" } } renders every link with target="_self", stores nothing, and returns the same link.

3. Declare target on the mark with a TipTap extension, and set it on the link in a transaction:

   const LinkTarget = Extension.create({
     name: "linkTarget",
     addGlobalAttributes() {
       return [
         {
           types: ["link"],
           attributes: {
             target: {
               default: null,
               parseHTML: (element) => element.getAttribute("target"),
               renderHTML: (attrs) => (attrs.target ? { target: attrs.target } : {}),
             },
           },
         },
       ];
     },
   });
   
   const declared = BlockNoteEditor.create({
     initialContent: doc(),
     extensions: [createExtension({ key: "linkTarget", tiptapExtensions: [LinkTarget] })],
   });
   declared.mount(document.getElementById("editor-declared"));
   
   console.log(JSON.stringify(linkMarkAttrs(declared)));
   // [{"target":null,"href":"https://example.org/"}]
   
   // The link's text, "x", spans positions 3 to 4.
   declared.transact((tr) => {
     const mark = declared.pmSchema.marks.link.create({ href: "https://example.org/", target: "_self" });
     tr.addMark(3, 4, mark);
   });
   
   console.log(JSON.stringify(linkMarkAttrs(declared)));
   // [{"target":"_self","href":"https://example.org/"}]
   console.log(JSON.stringify(declared.document[0].content[0]));
   // {"type":"link","href":"https://example.org/","content":[{"type":"text","text":"x","styles":{}}]}
   console.log(document.querySelector("#editor-declared a").outerHTML);
   // <a target="_blank" href="https://example.org/" rel="noopener noreferrer nofollow" classname="bn-inline-content-section" data-inline-content-type="link">x</a>
   
   declared.replaceBlocks(declared.document, declared.document);
   console.log(JSON.stringify(linkMarkAttrs(declared)));
   // [{"target":null,"href":"https://example.org/"}]

The mark's spec now has target, but the target in initialContent still arrives as null. After the transaction, the mark in the ProseMirror state has target: "_self", yet declared.document returns the link without it, and the editor renders the link with target="_blank", because links.HTMLAttributes is merged over the mark's own attribute. Loading that document back with replaceBlocks(), as a host does with a document it has saved, sets the mark's target to null again.

What this project does meanwhile

The BlockNote Editor module for Drupal (https://www.drupal.org/project/blocknote) stores the choice as a boolean style, newTab, on the text runs inside the link's own content, because a style round-trips where a mark attribute does not. A style mark is inclusive by default, so it survives editLink()'s insertText(), which keeps the marks across the text it replaces (decision record 0032 has the measurement). The module's own link form does not call editLink(), though: it repeats that function's insertText() and addMark() and then sets or clears the style over the same text in the same transaction, from an "Open in a new tab" checkbox in the form, and a test pins that the style survives an edit of both the URL and the text. The same style serves the module's own custom inline content type for links to site content, so both kinds of link carry the choice the same way.

The link's first run decides, and the rest has to be kept in line by hand. A plugin appended to every transaction copies the first run's flag onto the link's other runs, so text pasted into the middle of a new-tab link gains it, and takes the flag off any run that ends up outside a link, which typing at a link's end produces, since the style mark is inclusive and the link mark is not. The editor's own sign that a link opens in a new tab is a widget decoration drawn once at the end of the link, because the style's element for each run nests inside whatever other style marks the run carries and a sign drawn per run would repeat; it is hidden by default, and a theme may show it with one rule. The rendered page reads the first run only.

This works, but the choice lives beside the link's text rather than beside its href, where an integrator reading the stored document would not look for it, and a carrier that can differ from run to run has to be held uniform for a choice that belongs to the link as a whole.

What this asks for

One of, in order of preference:

• Let a host declare further attributes on link beyond href, the same way a custom inline content type declares its props, and carry them through nodeToBlock and blockToNode, so a stored link keeps them. That also means comparing them where nodeToBlock decides whether adjacent text belongs to the same link, which today compares href only (line 299), keeping them in editLink(), and letting a stored attribute win over the same attribute in links.HTMLAttributes when the link renders. links.HTMLAttributes from feat: Link customization options (BLO-913) #2666 already covers rendering, for every link at once; this is the storage half, and the "default link with an additional prop" a maintainer asked about in Distinguish link types (e.g. External vs Internal) #2479.
• Document that link is deliberately not extensible this way, and instead expose an official seam, comparable to InlineContentSpecs, for replacing or wrapping the built-in link type with one that declares extra attributes while keeping the toolbar, paste handling and node conversions that already assume a link-shaped mark exists. The answer on Override rendering of built-in blocks (Link) #1118 says customizing a link through the custom inline content API would be a major breaking change, so this may have to be a seam of its own.
• If neither is planned, say so here, so integrators stop rediscovering the same gap independently.

Related

• Distinguish link types (e.g. External vs Internal) #2479 asks for one such stored flag, to tell internal links from external ones.
• Override rendering of built-in blocks (Link) #1118 asks to customize how a link renders.
• feat: Link customization options (BLO-913) #2666 added links.HTMLAttributes and links.onClick, and fix: Link HTML attributes (BLO-915) #2687 fixed links.HTMLAttributes; both apply to every link alike.
• Open same-origin links in the same tab #3272 asks for same-origin links to open in the same tab.

AI use: I maintain the BlockNote module for Drupal. Its code, tests and documentation, this request and the reproduction behind it were made with AI coding agents that I direct.