CodeMirror gutters: add line references beside editable source

A fictional support tool displays an HTML notice beside a review conversation. A reviewer needs to say “check line 3” without making line numbers part of the HTML copied into the notice. Later, the author inserts a heading above that line. The review reference now needs its original revision, because a visible line number alone is not a permanent content identifier.

Add a line-number column

For an existing CodeMirror 6 application, include the extension in its editor configuration:

import { lineNumbers } from '@codemirror/view';

const noticeLineNumbers = lineNumbers();

Add noticeLineNumbers to that editor's extensions. Keep the current language, keymaps, and other setup. Check whether a convenience setup already supplies line numbers before adding the feature again.

The displayed numbers refer to document lines. A long source line can wrap onto several screen rows while remaining one document line. Resizing the panel therefore does not mean the source has gained newline characters.

To copy or save the actual HTML, read the document:

const noticeSource = view.state.doc.toString();

Here view is the initialized editor instance. Do not scrape the gutter and content DOM together to construct a file. Apart from including interface labels, DOM scraping can miss source outside the rendered viewport.

Make a custom marker column visible

A second gutter can explain a narrowly defined condition. This original example marks physically empty document lines with a small dot:

import { gutter, GutterMarker } from '@codemirror/view';

class EmptyLineMarker extends GutterMarker {
  toDOM() {
    const marker = document.createElement('span');
    marker.textContent = '·';
    marker.title = 'Empty source line';
    return marker;
  }
}

const emptyMarker = new EmptyLineMarker();
const emptyLineGutter = gutter({
  class: 'empty-source-lines',
  lineMarker(view, line) {
    return line.from === line.to ? emptyMarker : null;
  },
  initialSpacer: () => emptyMarker
});

Place the extensions in the intended order, for example [noticeLineNumbers, emptyLineGutter] within the editor's other extensions. The order of gutter extensions determines their column order. The spacer gives the marker column a width even where a line has no marker.

A line containing spaces has characters, so this condition does not mark it. Explain “empty source line” in nearby interface text if the distinction matters. A tooltip can supplement that explanation but is not the only way readers should discover the marker's meaning.

Give stored review markers a document position

The empty-line example derives each marker from the current line, so it needs no saved marker collection. A review bookmark or breakpoint is different: it must persist while the document changes.

The official gutter example uses a state field containing a range set, maps that set through each transaction's changes, and applies state effects to add or remove markers. Use that pattern when markers need an editing lifecycle. Keeping an array of old line numbers will point at different content after an insertion above them.

Also define what happens when the marked text is deleted. Position mapping supports an implementation; it does not decide whether the associated review comment is resolved, orphaned, or still relevant. Keep a durable comment identity and revision outside a transient gutter label.

Check what the reader can reference and copy

Use this three-line fixture in the development editor:

<h2>Collection notice</h2>

<p>Ask for the recorder at the reception desk.</p>

Expect line numbers 1 through 3 and an empty-line marker on line 2. Type a space on that empty line: the marker should disappear under the exact condition above. Insert a line before the paragraph and inspect its new number. Finally, capture view.state.doc.toString() and confirm that it contains the source characters without gutter numbers or dots.

The CodeMirror lint guide covers diagnostic markers with a checker's specific meaning. For a support conversation, attach the source revision and relevant text to a line reference so the next editor can still locate the issue after the notice changes.