Velite

Set up CodeGloss with Velite — a content build tool that compiles markdown/MDX into type-safe data collections.

This documentation site itself uses Velite + Next.js.

Install

npm install codegloss @codegloss/react velite

Configure Velite

Add remark-codegloss to your velite.config.ts. Use skipImport: true because the React wrapper is provided via the components map at render time. If you've declared a highlight in codegloss.config.ts (see Syntax Highlighters), thread it through so blocks are pre-highlighted at build:

Render compiled MDX

Velite compiles MDX content into a JS function body string. Pass CodeGloss via the components map when you render it:

No CSS import needed

CodeGloss bundles its styles inside Shadow DOM. There's nothing for you to import in your global stylesheet — the element registers itself when @codegloss/react is loaded.

With Next.js

Configure the Velite webpack plugin in next.config.ts:

The remark plugin runs during Velite's build step, so remarkPlugins goes in velite.config.ts only — not in any Next.js MDX config.

Consistent chrome on every code block (optional)

By default, only fences tagged with codegloss get the codegloss chrome (toolbar, line numbers, copy button). Plain fenced code blocks render as regular <pre> elements. If you'd rather have every code block on your site use the same visual, install @codegloss/shiki and add rehypeCodeglossPre to your rehype pipeline — it runs after rehype-shiki and rewrites every <pre><code> into a <code-gloss> element with the highlighted HTML baked in.

npm install @codegloss/shiki

Now every <pre><code> on your site renders inside a <code-gloss> element — same toolbar, line numbers, and copy button as your annotated blocks, with Shiki's highlighted HTML baked in at build time.

@codegloss/shiki also re-exports createShikiHighlighter and ShikiLikeHighlighter from codegloss/highlighters/shiki, so Shiki users can import everything from one package.