Reference

Defining a macro

A macro is described by the Macro type, which is the union of BlockMacro and InlineMacro.
Every macro provides:

• infos - the macro metadata (see MacroInfos).
• renderAs - "block" or "inline".
• render(params, rawBody) - a function returning the rendering AST.

import type {
  BlockMacro,
  MacroBlock,
  MacroParameterType,
} from "@xwiki/platform-macros-api";

// Parameter definitions.
const params = {
  message: { type: "string" },
} satisfies Record<string, MacroParameterType>;

// A block macro rendering its "message" parameter as a paragraph.
class InfoMacro implements BlockMacro<typeof params> {
  readonly infos = {
    id: "info",
    name: "Information",
    description: "Displays a message.",
    params,
    paramsDescription: { message: "The message to display." },
    defaultParameters: { message: "" },
    bodyType: "none",
  } as const;

  readonly renderAs = "block" as const;

  render(params: { message: string }): MacroBlock[] {
    return [
      {
        type: "paragraph",
        styles: {},
        content: [{ type: "text", content: params.message, styles: {} }],
      },
    ];
  }
}

Macros are made available to the front-end by registering them with the Macros Service. See Service API.

MacroInfos

Metadata describing a macro.

BlockMacro

A macro that renders as a block.

InlineMacro

A macro that renders as inline content.

Macro types

Macro parameters

MacroParameterType

The definition of a single macro parameter.

type MacroParameterType = (
  | { type: "boolean" }
  | { type: "float" }
  | { type: "string" }
) & { optional?: true };

The concrete TypeScript type of a parameter is derived from this definition: "boolean" maps to boolean, "float" to number ("float" is used instead of "number" to be more explicit for developers) and "string" to string. Setting optional to true makes the parameter optional.

Parameter type helpers

Advanced type-level helpers, mostly used internally to derive concrete parameter types.

Rendering AST

The render function returns an array of AST nodes: block macros return MacroBlock[] and inline macros return MacroInlineContent[].

MacroBlock

A block-level AST node, discriminated by its type.

MacroInlineContent

An inline AST node, discriminated by its type.

Supporting AST types

Type	Description
MacroText	A text node: content (string) and styles (MacroTextStyles).
MacroTextStyles	Optional text styling: bold, italic, strikethrough, underline, code, textColor, backgroundColor.
MacroBlockStyles	Optional block styling: cssClasses, textColor, backgroundColor, textAlignment (MacroAlignment).
MacroAlignment	One of "left", "center", "right", "justify".
MacroListItem	A list item: content, styles, optional checked.
MacroImage	An target (MacroLinkTarget), optional alt, widthPx, heightPx.
MacroLink	A link: target (MacroLinkTarget) and content (inline content, excluding nested links).
MacroLinkTarget	Either { type: "internal", rawReference } or { type: "external", url }.
MacroTableColumn	A table column: optional headerCell (content + styles) and widthPx.
MacroTableCell	A table cell: content, styles, optional rowSpan, colSpan.

Functions

eraseParamsTypeForMacroClass(macro)

Casts a typed macro class to a MacroClassWithUnknownParamsType, dropping its parameter shape. This is useful when macros with different parameter shapes need to be handled together, for example
when registering them. 

function eraseParamsTypeForMacroClass<
  Params extends Record<string, MacroParameterType>,
>(
  macro: new (...args: any[]) => Macro<Params>,
): MacroClassWithUnknownParamsType;

Returns the same macro class, retyped without its parameter shape.