Link Extension Configuration

/**
 * Creates a Link mark extension for Tiptap editor
 * @returns Configured Link mark extension
 */
const Link: Mark<LinkOptions>;

import { Editor } from "@tiptap/core";
import { Link } from "@tiptap/extension-link";

// Basic configuration
const editor = new Editor({
  extensions: [
    Link.configure({
      openOnClick: true,
      autolink: true,
    }),
  ],
});

// Advanced configuration with custom protocols
const editor = new Editor({
  extensions: [
    Link.configure({
      openOnClick: true,
      autolink: true,
      linkOnPaste: true,
      protocols: ['ftp', 'git', { scheme: 'custom', optionalSlashes: true }],
      defaultProtocol: 'https',
      HTMLAttributes: {
        target: '_blank',
        rel: 'noopener noreferrer nofollow',
        class: 'custom-link',
      },
      isAllowedUri: (url, { defaultValidate, protocols, defaultProtocol }) => {
        // Custom validation logic
        if (url.startsWith('./') || url.startsWith('../')) {
          return true; // Allow relative URLs
        }
        return defaultValidate(url);
      },
      shouldAutoLink: (url) => {
        // Don't auto-link localhost URLs
        return !url.includes('localhost');
      },
    }),
  ],
});

interface LinkOptions {
  /**
   * If enabled, the extension will automatically add links as you type.
   * @default true
   */
  autolink: boolean;

  /**
   * An array of custom protocols to be registered with linkifyjs.
   * @default []
   */
  protocols: Array<LinkProtocolOptions | string>;

  /**
   * Default protocol to use when no protocol is specified.
   * @default 'http'
   */
  defaultProtocol: string;

  /**
   * If enabled, links will be opened on click.
   * @default true
   */
  openOnClick: boolean | DeprecatedOpenWhenNotEditable;

  /**
   * If enabled, the link will be selected when clicked.
   * @default false
   */
  enableClickSelection: boolean;

  /**
   * Adds a link to the current selection if the pasted content only contains an url.
   * @default true
   */
  linkOnPaste: boolean;

  /**
   * HTML attributes to add to the link element.
   * @default { target: '_blank', rel: 'noopener noreferrer nofollow', class: null }
   */
  HTMLAttributes: Record<string, any>;

  /**
   * A validation function which is used for configuring link verification for preventing XSS attacks.
   * Only modify this if you know what you're doing.
   * @param url - The URL to be validated
   * @param ctx - Validation context with default validation function and protocol info
   * @returns True if the URL is valid, false otherwise
   */
  isAllowedUri: (
    url: string,
    ctx: {
      defaultValidate: (url: string) => boolean;
      protocols: Array<LinkProtocolOptions | string>;
      defaultProtocol: string;
    }
  ) => boolean;

  /**
   * Determines whether a valid link should be automatically linked in the content.
   * @param url - The URL that has already been validated
   * @returns True if the link should be auto-linked; false if it should not be auto-linked
   */
  shouldAutoLink: (url: string) => boolean;

  /**
   * @deprecated Use the shouldAutoLink option instead.
   * A validation function that modifies link verification for the auto linker.
   * @param url - The url to be validated
   * @returns True if the url is valid, false otherwise
   */
  validate: (url: string) => boolean;
}

interface LinkProtocolOptions {
  /**
   * The protocol scheme to be registered.
   * @example 'ftp'
   * @example 'git'
   */
  scheme: string;

  /**
   * If enabled, it allows optional slashes after the protocol.
   * @default false
   */
  optionalSlashes?: boolean;
}

// String protocols
const protocols = ['ftp', 'ssh', 'git'];

// Object protocols with options
const protocols = [
  'ftp',
  { scheme: 'git', optionalSlashes: true },
  { scheme: 'custom', optionalSlashes: false },
];

const editor = new Editor({
  extensions: [
    Link.configure({
      protocols,
      defaultProtocol: 'https',
    }),
  ],
});

/**
 * Default Link extension configuration
 */
const defaultOptions: LinkOptions = {
  openOnClick: true,
  enableClickSelection: false,
  linkOnPaste: true,
  autolink: true,
  protocols: [],
  defaultProtocol: 'http',
  HTMLAttributes: {
    target: '_blank',
    rel: 'noopener noreferrer nofollow',
    class: null,
  },
  isAllowedUri: (url, ctx) => !!isAllowedUri(url, ctx.protocols),
  validate: url => !!url,
  shouldAutoLink: url => !!url,
};

interface LinkAttributes {
  /** Link URL */
  href: string | null;
  /** Link target (_blank, _self, etc.) */
  target: string | null;
  /** Link relationship (noopener, noreferrer, etc.) */
  rel: string | null;
  /** CSS class name */
  class: string | null;
}

// Configure HTML attributes
const editor = new Editor({
  extensions: [
    Link.configure({
      HTMLAttributes: {
        target: '_blank',
        rel: 'noopener noreferrer nofollow',
        class: 'custom-link-class',
        'data-track': 'link-click',
      },
    }),
  ],
});

/** @deprecated The default behavior is now to open links when the editor is not editable */
type DeprecatedOpenWhenNotEditable = 'whenNotEditable';