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
-
starlight-markdown-blocks
is a Starlight plugin. Install it by running the following command in your terminal:Terminal window npm i starlight-markdown-blocksTerminal window pnpm add starlight-markdown-blocksTerminal window yarn add starlight-markdown-blocks -
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},}),],}),],}); -
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.
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:
:::ideaI 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.
Next steps
Learn how to add different kinds of blocks.