Turn code blocks into interactive explanations.

CodeGloss adds clickable, token-level annotations and connection arcs to fenced code blocks. One remark plugin, one Web Component, every framework.

$npm install codegloss

Before

1function fibonacci(n) {
2  const memo = {};
3
4  function fib(k) {
5    if (k <= 1) return k;
6    if (memo[k]) return memo[k];
7    memo[k] = fib(k - 1) + fib(k - 2);
8    return memo[k];
9  }
10
11  return fib(n);
12}

After

Works with

Markdown React Vue Svelte Next.js Astro VitePress Docusaurus Vanilla HTML

Interactive Annotations

Click any highlighted token to reveal an explanation. Annotations are defined in JSON alongside your code — no custom syntax to learn.

Connection Arcs

Draw visual arcs between related annotations. Gutter lines connect concepts with click-to-explain popovers.

MDX Native

Write fenced code blocks with a `codegloss` tag. The remark plugin detects them and emits CodeGloss components at build time.

Why CodeGloss?

Comments explain what. Annotations explain why.

Code comments are static and invisible to readers skimming a tutorial. CodeGloss annotations are interactive — readers click what they don't understand and skip what they already know.

One package, every framework.

A single Web Component under the hood, with thin wrappers for React, Vue, and Svelte. Works with any markdown pipeline via a remark plugin, or drop the custom element into plain HTML.

Annotations live next to your code, not inside it.

Define annotations in a JSON block alongside the fenced code. Your source stays clean, and annotations can be updated without touching the code itself.

Quick start

Install

npm install codegloss

Configure your MDX pipeline

import createMdx from '@next/mdx';
import remarkCodegloss from 'codegloss/remark';

const withMdx = createMdx({
  options: {
    remarkPlugins: [remarkCodegloss],
  },
});

Write annotated code in MDX

```js codegloss fibonacci.js
function fibonacci(n) {
  const memo = {};
  // ...
}
```

```json annotations
{
  "annotations": [{
    "id": "a1",
    "token": "memo",
    "line": 1,
    "occurrence": 0,
    "title": "Cache",
    "text": "Stores computed values."
  }]
}
```

Read the docs →