Aside
The Aside
block type renders an aside (also known as “callout” or “admonition”) in the same style as Starlight’s built-in asides.
This is a custom aside style.
How many stars in the Andromeda constellation have planets?
Usage
Import Aside
in astro.config.mjs
and use it in the starlightMarkdownBlocks
configuration:
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: '💡' }), }, }), ], }), ],});
Options
The Aside
block accepts the following options.
label
(required)
Type: string
The default label that will be shown when your block is used without a custom label.
For example, an :::idea
block might have a default label of "Idea"
.
You can override this default in your Markdown content by specifying a custom label for that instance, e.g. :::idea[Custom label]
.
color
Type: "blue" | "purple" | "red" | "orange" | "green" | "accent"
Default: "accent"
The color from Starlight’s palette to use for the aside’s border, background, and heading text color. Defaults to the current theme’s accent color.
icon
Type: string
The icon to display in the aside’s heading. This can be any HTML content. For example, you can provide an SVG or use an emoji.
// Aside using an emoji as its iconAside({ label: 'Woah!', icon: '🤯' }),
// Aside using an SVG as its iconAside({ label: 'Question', icon: '<svg xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 24 24"><path d="M11.29 15.29a1.58 1.58 0 0 0-.12.15.76.76 0 0 0-.09.18.64.64 0 0 0-.06.18 1.36 1.36 0 0 0 0 .2.84.84 0 0 0 .08.38.9.9 0 0 0 .54.54.94.94 0 0 0 .76 0 .9.9 0 0 0 .54-.54A1 1 0 0 0 13 16a1 1 0 0 0-.29-.71 1 1 0 0 0-1.42 0ZM12 2a10 10 0 1 0 10 10A10 10 0 0 0 12 2Zm0 18a8 8 0 1 1 8-8 8 8 0 0 1-8 8Zm0-13a3 3 0 0 0-2.6 1.5 1 1 0 1 0 1.73 1A1 1 0 0 1 12 9a1 1 0 0 1 0 2 1 1 0 0 0-1 1v1a1 1 0 0 0 2 0v-.18A3 3 0 0 0 12 7Z"/></svg>',}),
element
Type: string
Default: "aside"
The HTML element to use as the wrapper for the aside.
By default, an <aside>
element is used to match Starlight’s built-in asides.
However, an <aside>
implies that the block’s content is complementary or secondary information, so you could choose to specify a different element if it is more appropriate for your callout type.
Styling
If you want to customize your asides further, you can do so using custom CSS.
Custom asides have a classname of starlight-custom-aside--BLOCK-NAME
that can be targeted in CSS.
For example, :::idea
asides could be styled like this to customize their appearance:
.starlight-custom-aside--idea { border: 1px solid var(--sl-color-green); border-radius: 0.5rem;
.starlight-aside__title { text-transform: uppercase; }}