Markdown plugins
Some features change the Markdown of a page outside its code blocks, such as code tabs and inline code highlighting. codeblocks() adds a Markdown plugin for each of these features. The starlight-codeblocks/markdown subpath exports the same plugins, for sites that put their Markdown plugins in order themselves.
Add the plugins yourself
Section titled “Add the plugins yourself”Astro 7 gives its Markdown to Sätteri. Add the plugins to mdastPlugins of the Sätteri processor. codeblocks() then adds only the plugins that are not in the list. It puts each one before the listed plugin that comes after it in the table, so the plugins stay in the correct order:
import { satteri } from '@astrojs/markdown-satteri';import { mdastCodeTabs } from 'starlight-codeblocks/markdown';
export default defineConfig({ markdown: { processor: satteri({ mdastPlugins: [glossaryLinks(), mdastCodeTabs({ control: 'menu' })] }), }, integrations: [starlight({ plugins: [codeblocks()] })],});In this example, glossaryLinks() runs before all the plugins of the package. Each plugin takes the settings of its option in the options reference. The settings that you give to a plugin apply in place of the options of codeblocks().
A plugin for a feature that is off in codeblocks() stops the build. The feature also needs parts that codeblocks() adds only when the feature is on. A plugin in the list two times also stops the build.
The group
Section titled “The group”mdastCodeblocks(options) returns the plugins of every feature that is on, in the correct order. With no argument on a site with codeblocks(), it reads the options that you gave to codeblocks(), and codeblocks() adds no Markdown plugin. Do not also list a plugin that is in the group.
import { mdastCodeblocks } from 'starlight-codeblocks/markdown';
processor: satteri({ mdastPlugins: [mdastCodeblocks(), glossaryLinks()] }),Plugins
Section titled “Plugins”The table gives the plugins in the order that the group adds them.
| Plugin | Option | Feature |
|---|---|---|
mdastWhitespace() |
whitespace |
Visible whitespace: keeps the spaces at the end of each line of code |
mdastMentions(notation) |
mentions |
Code mentions: changes each mention link with no code block into text |
mdastPermalinks() |
permalinks |
Line permalinks: warns about two code blocks with the same id |
mdastCodeTabs(settings) |
codeTabs |
Code tabs |
mdastInlineHighlighting(settings) |
inlineHighlighting |
Inline code highlighting |
mdastSwatches(settings) |
swatches |
Colour swatches in the text of a page and in inline code |
mdastMentions() takes the settings of the notation option, because it reads directives with the same comment syntax as the code blocks. mdastInlineHighlighting() must come before mdastSwatches(), so that highlighted inline code gets no swatch.
Each plugin also takes a logger as its last argument, an object with a warn(message) function. The default writes to the console.
The unified() processor
Section titled “The unified() processor”On a site with Astro’s unified() processor, put the plugins in remarkFromSatteri(). It changes a list of Sätteri plugins into one remark plugin:
import { unified } from '@astrojs/markdown-remark';import { mdastCodeTabs, remarkFromSatteri } from 'starlight-codeblocks/markdown';
markdown: { processor: unified({ remarkPlugins: [remarkFromSatteri([mdastCodeTabs({ control: 'menu' })])] }),},Without codeblocks()
Section titled “Without codeblocks()”The plugins work without codeblocks(), with these differences:
- Code tabs need the
directivefeature of the processor. Starlight turns it on; on another site, usesatteri({ features: { directive: true } }). - Inline code highlighting and swatches in the text of a page need stylesheets that only
codeblocks()adds. - The texts of code tabs and swatches are in English.
Related
Section titled “Related”- Expressive Code plugins: the plugins for code blocks, and how to put them in order.
- Plugin compatibility: other plugins and Markdown processors.