Astro / Starlight
CodeGloss works with Astro (and Starlight) using the remark plugin in HTML mode. Since Astro renders pages to static HTML, we emit raw <code-gloss> elements and load the runtime via a client-side script.
Install
npm install codeglossConfigure the remark plugin
Add remark-codegloss to your astro.config.mjs with output: 'html'. If you've declared a highlight in codegloss.config.ts (see Syntax Highlighters), thread it through so blocks are pre-highlighted at build:
For plain Astro (without Starlight), add the plugin under the same markdown.remarkPlugins key and load the runtime script in your layout's <head>.
Copy the runtime to public/
Astro serves static assets from public/. Create a prebuild script that copies the CodeGloss runtime there:
Add it to your build script:
Write annotated code blocks
Use the standard fenced codegloss syntax in any .md or .mdx content file:
The remark plugin transforms these into <code-gloss> HTML elements at build time. The runtime script in the <head> registers the custom element on the client.
Why HTML mode?
Astro processes markdown through remark/rehype and emits static HTML — it doesn't use React or MDX JSX at runtime. The output: 'html' mode tells the plugin to emit raw HTML nodes instead of JSX, which Astro passes through to the final page unchanged.
No CSS import needed
The Web Component bundles its styles via Shadow DOM. There's nothing to add to your global stylesheet.