Macros

Macros are a way to provide custom blocks or inline content in BlockNote. They are persisted when the document is saved.

Markdown support is performed through XWiki's extended syntax (curly braces).

Macros have a set of parameters, and can provide default parameters in case some of them are missing. Rendering is done through a React component.

Current limitations

Macros:

• Are client-side only (no server-side support)
• Must be registered by the part integrating BlockNote Headless
• Cannot be edited (read-only)
• Cannot have nested content

API

Macros are provided through the editorProps.macros property from the c-blocknote-view component, which also provides a DEFAULT_MACROS record containing a set of common-use macros.

Custom ones can be created through the createMacro utility helper.

/**
 * Arguments for creating a macro
 *
 * @since 0.20
 */
type MacroCreationArgs<Parameters extends Record<string, MacroParameterType>> =
  {
    /** The macro's name */
    name: string;

    /** The macro's description */
    description: string;

    /** The macro's render type (block or inline content) */
    renderType: "block" | "inline";

    /** Definition of every parameter */
    parameters: Parameters;

    /**
     * Default value of every required parameter
     *
     * Optional parameters will be omitted from the default object
     */
    defaultParameters: FilterUndefined<
      GetConcreteMacroParametersType<Parameters>
    >;

    /** Should the macro be hidden from the slash menu? */
    hidden?: boolean;

    /**
     * React render function
     *
     * @param parameters - The macro's parameters ; optional fields may be absent or equal to `undefined`
     * @param contentRef - The editable section of the block, handled by BlockNote
     *
     * @returns The React node to render the macro as
     */
    render(
      parameters: GetConcreteMacroParametersType<Parameters>,
      contentRef: (node: HTMLElement | null) => void,
    ): React.ReactNode;
  };

/**
 * Description of a macro type
 *
 * @since 0.20
 */
type MacroParameterType = (
  | { type: "boolean" }
  // We use 'float' instead of 'number' here to make it more explicit to developers
  | { type: "float" }
  | { type: "string" }
  | { type: "stringEnum"; possibleValues: string[] }
) & {
  // Make the parameter optional
  optional?: true;
};

/**
 * Create a macro.
 *
 * This will effectively return a `Macro` object
 *
 * @param args - Informations about the macro to create
 *
 * @returns The macro
 *
 * @since 0.20
 */
function createMacro<Parameters extends Record<string, MacroParameterType>>({
  name,
  description,
  parameters,
  defaultParameters,
  hidden,
  render,
  renderType,
}: MacroCreationArgs<Parameters>): Macro;