Examples

Live demos rendered through remark-codegloss. Each example below is a standard MDX fenced code block in this page's source — the plugin transforms them into <code-gloss> Web Component instances at build time.

Click any underlined token to expand its annotation. Click a connection arc (or one of its endpoint dots) to see why those annotations are related.

---

Memoized Fibonacci

A classic memoization pattern. Annotations explain the cache lifecycle, and connections link the table declaration to its lookups.

---

Event Delegation

A pattern where a single listener on a parent element handles events for multiple children.

---

Data Flow — Right-side arrows

Connections can render on the right side of the code block via "side": "right", anchored at each line's end rather than in the fixed gutter. Combined with "arcs": { "arrowhead": true }, arcs become explicit flow indicators — the arrow points at the to endpoint, the from endpoint stays a dot.

arrowhead is set per block, not per connection — the example below applies arrowheads to all three arcs, the two left-side ones (q1→q2, q4→q2) as well as the single right-side one (q3→q5).

---

Popover callouts

Annotation callouts normally render inline — clicking a token expands a row of context directly below its line. For denser docs where vertical expansion would shuffle the page, set callouts.popover: true to present the callout as a floating popover anchored to the click position instead.

Annotation and connection popovers are independent surfaces: a reader can have an annotation popover and an arc popover open at the same time. Inline and popover presentations of the same annotation are mutually exclusive.

---

Pre-opened callouts (walkthrough style)

For in-doc walkthroughs you can surface a specific annotation or connection on first render via defaultOpen. At most one annotation callout and one connection popover can be pre-opened per block — if multiple are marked, the last one in its array wins (CSS-cascade style).

---

Minimal — No Annotations

A codegloss block without a following annotations block renders as a plain code viewer with line numbers and a toolbar.

---

Other usage patterns

The examples above all use the MDX fenced code block syntax with the remark plugin. CodeGloss also works as a direct React component or a vanilla HTML Web Component.

React (direct)

Import CodeGloss from @codegloss/react and pass props directly — no remark plugin or MDX needed:

Vanilla HTML

Drop a <code-gloss> custom element on any page. No build step required:

HTML output mode (plain markdown pipelines)

For non-MDX pipelines (marked, markdown-it, remark → rehype → HTML), use the remark plugin with output: 'html'. This emits raw <code-gloss> elements instead of JSX:

Load the runtime on the page so the custom element registers: