Getting Started

CodeGloss renders interactive, annotated code blocks. Highlight tokens, attach inline callouts, and draw connection arcs between related concepts.

It ships as a Web Component so it works in any framework — or no framework at all.

Installation

npm install codegloss

That installs the <code-gloss> web component, the remark plugin, themes, and the config helpers. If you're using a framework, pick the matching wrapper in the Pick your usage section below — each tab shows the exact install command.

Requirements

  • Node 18+ for build tooling.
  • ESM consumers. The package ships as ES modules only; use a bundler (Vite, Next, webpack 5, Rollup, esbuild) or import from an ESM Node config. The codegloss/remark subpath keeps a CJS build for older remark config pipelines (Docusaurus with .ts configs, etc.).

Pick your usage

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

npm install codegloss @codegloss/react
Setup
import remarkCodegloss from 'codegloss/remark';

const withMdx = createMdx({
  options: {
    remarkPlugins: [remarkCodegloss],
  },
});
Markdown
```js codegloss greet.js
function greet(name) {
  return "Hello, " + name + "!";
}
```

```json annotations
{
  "annotations": [
    { "id": "a1", "token": "name", "line": 0,
      "occurrence": 0, "title": "Parameter",
      "text": "The name to greet." }
  ]
}
```

See the Remark Plugin docs for output modes (mdx for React/MDX, html for plain markdown pipelines).

Here's what you get

This is a live CodeGloss block — click any underlined token to expand its annotation, or click a connection arc in the gutter:

function greet(name) {
  const message = "Hello, " + name + "!";
  console.log(message);
  return message;
}

greet("world");

Next steps