Skip to content

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.

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:

astro.config.mjs
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.

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.

astro.config.mjs
import { mdastCodeblocks } from 'starlight-codeblocks/markdown';
processor: satteri({ mdastPlugins: [mdastCodeblocks(), glossaryLinks()] }),

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.

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:

astro.config.mjs
import { unified } from '@astrojs/markdown-remark';
import { mdastCodeTabs, remarkFromSatteri } from 'starlight-codeblocks/markdown';
markdown: {
processor: unified({ remarkPlugins: [remarkFromSatteri([mdastCodeTabs({ control: 'menu' })])] }),
},

The plugins work without codeblocks(), with these differences:

  • Code tabs need the directive feature of the processor. Starlight turns it on; on another site, use satteri({ 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.