Block Formatter

Block-level type conversion and decoration for selected blocks, including partial list formatting.

Access:

app.getService('blockFormatter')

App code:

const blockFormatter = app.getService('blockFormatter');

Plugin:

const blockFormatter = this.app.getService('blockFormatter');

canFormat#

Returns whether the current selection has at least one formattable block or a valid list-items context for formatting.

Returns: boolean

blockFormatter.canFormat();

applyDecorations#

Applies attrs, classes, and/or styles to blocks matching the current selection filters, emits blocks:decorations:change when any block changed, and returns the changed blocks.

Parameters:

• options (object) — object with the keys below
  • attrs (object) — HTML attributes ({ name: value }; true / null sets a boolean attribute)
  • classes (string | string[]) — CSS class names to toggle (string or array)
  • styles (object) — CSS declarations to toggle ({ color: '#f00' } or { backgroundColor: 'yellow' })
  • editable (boolean) — when true/false, only target blocks that are/aren't editable (default: no filter)
  • types (Array) — only target these block type(s)
  • excludeTypes (Array) — exclude these block type(s)
  • topLevelOnly (boolean) — only target top-level blocks (default false)
  • includeInline (boolean) — include inline blocks (default false)
  • partial (boolean) — include blocks that are only partially selected (default false)

Returns: Block[]

blockFormatter.applyDecorations({ classes: ['highlight'] });

getContext#

Analyzes the current block selection and returns selected, formattable, ignored, partial list, list-items, and canFormat flags used by format().

Returns: { selected: Block[], formattable: Block[], ignored: Block[], partialItems: object, listItemsContext: object, isSingle: boolean, insideCellOnly: boolean, canFormat: boolean }

blockFormatter.getContext();

format#

Converts selected blocks to the target type (text, heading, list, todo, quote, pre, etc.), handling list-item selections, partial lists, toggle-to-text behavior, caret save/restore, and adjacent list merging. Emits blocks:format and returns affected Block instances.

Parameters:

• targetType (string) — target block type, e.g. 'text', 'heading', 'list', 'todo', 'quote', 'pre'
• options (object) — object with the keys below
  • headingLevel (number) — heading level (1-6) when targetType is 'heading' (default 2)
  • level (number) — alias for headingLevel
  • listTag (string) — list tag when targetType is 'list': 'ul' (default) or 'ol'
  • tag (string) — alias for listTag
  • attrs (object) — HTML attributes to apply to the resulting blocks
  • classes (string | string[]) — CSS class names to apply to the resulting blocks
  • styles (object) — CSS declarations to apply to the resulting blocks

Returns: Block[]

blockFormatter.format('heading', { headingLevel: 2 });