Skip to content
Starlight Markdown Blocks

Custom blocks API reference

Custom block objects

A custom block can specify the following properties:

label

Type: string

The default label to use for this block if no label is provided in Markdown.

Users can specify a custom label inside square brackets after the block name, e.g. :::block[Custom label].

css

Type: string[]

An optional array of CSS files to load for this block type. Values can be paths relative to your project root like "./src/block-style.css" or NPM module specifiers like "@me/my-package/styles.css".

render() (required)

Type: (context: RenderContext) => Element | Element[]

A callback function to render the markup for this block. It receives information for the current block instance and must return an abstract syntax tree representation of the HTML to render.

Starlight Markdown Blocks uses a remark plugin under the hood and uses the Markdown Abstract Syntax Tree (mdast) format for the render function.

The following example shows a selection of what mdast nodes can look like:

const rawHtmlNode = { type: 'html', value: '<div>Example</div>' };
const textNode = { type: 'text', value: 'A plain text node' };
const paragraphNode = { type: 'paragraph', children: [textNode] };

Use the h() utility function to simplify creating AST nodes representing HTML elements.

RenderContext

A custom block’s render() function will be called with a RenderContext object with the following properties:

blockName

Type: string

The name of the current block, e.g. "idea" for an :::idea block.

labelText

Type: string

The plain text content of the label for the current block. This can be useful for accessible labels that don’t support rich markup or for checking that a label value is set.

label

Type: Array<PhrasingContent>

Abstract syntax tree (AST) representing the label for the current block. Use this AST to render the label in the correct location in your block.

The content represents the default label or a user-provided label, e.g. "Idea" for an :::idea block or "Try this!" for an :::idea[Try this!] block.

This may include inline elements for user-provided labels that include Markdown formatting, e.g.

:::idea[Try the `Code` component]
children

Type: Array<BlockContent | DefinitionContent>

Abstract syntax tree (AST) representing the children of the current block.

attributes

Type: Record<string, string | null | undefined>

A map of any user-defined attributes added to the block in Markdown.

The directive syntax supports providing attributes in curly braces when specifying a block, for example:

:::button{variant="primary" href="/page"}
Click me!
:::

Your render function can then decide how to use these attributes.

h()

Type: (el: string, attrs?: Properties, children?: Element[]) => Element

A utility function for quickly creating an AST representation of an HTML element. Use this to template the HTML for your Markdown block.

h() expects the following arguments:

  • An HTML tag name like "p" or "blockquote".
  • An object representing attributes for this element like { class: "my-element" }.
  • An array of children that this element contains, which can themselves be created with h() or can be other mdast node types.

The following example renders a <figure class="picture-frame"> element containing the block’s children with a caption using the user-provided label:

h('figure', { class: 'picture-frame' }, [
  h('div', { class: 'picture' }, children),
  h('figcaption', {}, label),
]);

Types

You can import the MarkdownBlock type to help write custom block objects. This can be helpful when writing custom blocks in separate files or returning them from functions.

import type { MarkdownBlock } from 'starlight-markdown-blocks';


const ExampleBlock = (): MarkdownBlock => ({
  render: ({ h }) =>
    h('div', {}, [
      // ...
    ]),
});