Add a configurable Markdown link serialization policy #3035

What’s broken?

The Markdown exporter does not provide a public option to control how links are serialized.

When a URL-only link is created in BlockNote, blocksToMarkdownLossy may serialize it as a bare URL:

https://example.com

This is valid in GFM, but it loses the explicit distinction between ordinary text and a Markdown link. It also makes it difficult for applications to enforce a consistent Markdown export policy.

What did you expect to happen?

Applications should be able to choose whether links are serialized as:

https://example.com

or explicitly as:

[https://example.com](https://example.com)

For links with a separate label, the explicit format should remain:

[Documentation](https://example.com)

The default behavior should remain unchanged for backward compatibility.

Steps to reproduce

1. Create a BlockNote editor.
2. Insert a link where the displayed text is the same as the URL.
3. Export the document with blocksToMarkdownLossy.
4. Observe that the result may contain a bare URL instead of explicit Markdown link syntax.

Example:

const markdown = editor.blocksToMarkdownLossy(editor.document);
console.log(markdown);

Observed output:

https://example.com

Desired opt-in output:

[https://example.com](https://example.com)

BlockNote version

v0.54.0

Environment

React application, macOS

Proposed API

One possible API would be an export option:

editor.blocksToMarkdownLossy(editor.document, {
  linkStyle: "explicit",
});

Possible values:

type MarkdownLinkStyle = "auto" | "explicit";

Where:

• "auto" preserves the current behavior.
• "explicit" always emits [label](url) for links.
• Links with different labels continue to emit [label](url).

The option could be exposed through the lower-level Markdown exporter API as well.

Additional context

We initially implemented an application-level HTML-to-Markdown serializer only to change this link behavior. However, that requires duplicating BlockNote’s complete Markdown serialization logic and creates compatibility and maintenance risks when BlockNote changes its exporter.

A public link serialization option or hook would allow applications to customize this behavior without forking the whole serializer.

Contribution

I’d be interested in contributing a fix for this issue.