Skip to content
Starlight Markdown Blocks

Getting Started

This plugin extends Starlight’s Markdown asides syntax, so that it can be used to render custom block types.

For example, just like you can use :::tip to render an aside in Starlight, you can use this plugin to add support for syntax such as :::my-custom-block and control how that renders.

Prerequisites

You will need to have a Starlight website set up. If you don’t have one yet, you can follow the “Getting Started” guide in the Starlight docs to create one.

Installation

  1. starlight-markdown-blocks is a Starlight plugin. Install it by running the following command in your terminal:

    Terminal window
    npm i starlight-markdown-blocks

  2. Add the plugin to your Starlight configuration in the astro.config.mjs file.

    astro.config.mjs
    import starlight from '@astrojs/starlight';
    import { defineConfig } from 'astro/config';
    import starlightMarkdownBlocks from 'starlight-markdown-blocks';
    

    export default defineConfig({
      integrations: [
        starlight({
          title: 'My Docs',
          plugins: [
            starlightMarkdownBlocks({
              blocks: {
                // Blocks configuration
              },
            }),
          ],
        }),
      ],
    });

  3. You can now add support for custom blocks by adding entries to the blocks configuration object.

Configuring blocks

Configure blocks by adding entries to the blocks object passed to the starlightMarkdownBlocks() plugin. Each key in blocks will become a name you can use in your Markdown files. For example, if you add an idea key, you will be able to use :::idea in your Markdown files to render that block type.

The value of each block configuration defines how it should render. There are built-in block renderers for common use cases and you can also write your own.

Configuration example

The following configuration example adds an :::idea block using the built-in Aside helper that renders like Starlight’s asides but with a custom label, color, and icon. It also adds a custom :::figure block to support authoring HTML <figure> and <figcaption> elements without having to write HTML directly.

astro.config.mjs
import starlight from '@astrojs/starlight';
import { defineConfig } from 'astro/config';
import starlightMarkdownBlocks, { Aside } from 'starlight-markdown-blocks';


export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      plugins: [
        starlightMarkdownBlocks({
          blocks: {
            idea: Aside({ label: 'Idea', color: 'green', icon: '💡' }),
            figure: {
              render: ({ h, label, children }) =>
                h('figure', {}, [...children, h('figcaption', {}, label)]),
            },
          },
        }),
      ],
    }),
  ],
});

With this configuration, Markdown documents can use these new custom block types:

example.md
:::idea
I just thought of something!
:::


:::figure[— Donna Haraway, <cite>A Cyborg Manifesto</cite>]


> One is too few, and two is only one possibility.


:::

I just thought of something!

One is too few, and two is only one possibility.

— Donna Haraway, A Cyborg Manifesto

Next steps

Learn how to add different kinds of blocks.