Warning
This repository is experimental. Expect breaking changes and unstable APIs.
This package provides visual (WYSIWYM) editing for LaTeX and Typst in the CodeMirror 6 editor.
Visual mode decorates the live CodeMirror document instead of maintaining a separate editable DOM tree. The source remains authoritative, and edits are applied as normal CodeMirror transactions.
- Source and visual editing modes over the same CodeMirror document
- Built-in visual adapters for LaTeX and Typst
- Visual headings, emphasis, lists, colors, tables, figures, and captions
- Interactive equations with optional MathLive
- Table layouts with editable cells and row/column controls
- Single and compound figure layouts, including subfigures and captions
- Inline source reveal when the cursor enters visually concealed markup
- Image resolution for external URLs and project-relative files
- Light and dark themes with configurable colors and spacing
- Built-in formatting toolbar with APIs for replacing it with custom UI
- Extensible language, widget, table, and figure adapters
CodeMirror language support can be used alongside the visual layer for syntax highlighting, completion, folding, linting, and other editor services.
npm install codemirror-visual-markupImport the bundled visual styles:
import 'codemirror-visual-markup/dist/styles.css';mathlive is an optional peer dependency. Install it when interactive equation editing is required:
npm install mathliveimport { EditorState } from '@codemirror/state';
import { EditorView } from '@codemirror/view';
import { latex } from 'codemirror-lang-latex';
import { DualVisualEditor } from 'codemirror-visual-markup';
import 'codemirror-visual-markup/dist/styles.css';
const view = new EditorView({
state: EditorState.create({
doc: '\\section{Introduction}\n\nText with \\textbf{visual formatting} and $E = mc^2$.',
extensions: [latex()]
})
});
const editor = new DualVisualEditor(
document.querySelector('#editor'),
view,
{
language: 'latex',
initialMode: 'visual'
}
);For Typst, use your normal Typst CodeMirror language extension and set language: 'typst'.
DualVisualEditor adds source/visual mode controls, the formatting toolbar, theme support, and math hover support around an existing EditorView.
const editor = new DualVisualEditor(container, view, {
language: 'latex', // 'latex', 'typst', or a registered language
initialMode: 'visual', // 'source' or 'visual'
showCommands: false, // show concealed source syntax in visual mode
showToolbar: true, // show the bundled formatting toolbar
enableMathHover: true, // source-mode math preview
theme: 'light' // 'light' or 'dark'
});Useful methods include:
editor.setMode('source');
editor.toggleMode();
editor.setLanguage('typst');
editor.toggleCommandVisibility();
editor.toggleToolbar();
editor.setTheme('dark');
editor.updateConfig({ showToolbar: false });
editor.destroy();DualLatexEditor is a convenience subclass with the language fixed to LaTeX.
If you already provide your own editor chrome, use the visual extension directly:
import { EditorState } from '@codemirror/state';
import { EditorView } from '@codemirror/view';
import {
setVisualState,
visualExtension
} from 'codemirror-visual-markup';
const view = new EditorView({
state: EditorState.create({
doc: '\\section{Title}',
extensions: [visualExtension()]
}),
parent: document.querySelector('#editor')
});
view.dispatch({
effects: setVisualState.of({
enabled: true,
language: 'latex',
showCommands: false,
maxDepth: 12
})
});External image URLs using http:, https:, data:, or blob: are displayed directly.
For project-relative image paths, provide an image resolver. The resolver receives a normalized path relative to the current document and returns a browser-readable URL.
import {
createImageResolver,
imageResolver
} from 'codemirror-visual-markup';
const resolver = createImageResolver(
() => currentDocumentPath,
async resolvedPath => {
const file = await loadProjectFile(resolvedPath);
if (!file) return null;
return URL.createObjectURL(file);
}
);
const view = new EditorView({
state: EditorState.create({
doc: '\\includegraphics{figures/result.png}',
extensions: [
imageResolver.of(resolver)
]
})
});
// When the editor is no longer used:
resolver.dispose?.();resolveImagePath(currentPath, src) is also exported when only path normalization is needed.
const editor = new DualVisualEditor(container, view, {
language: 'latex',
showToolbar: false
});The toolbar can also be shown or hidden later:
editor.toggleToolbar();
// or
editor.updateConfig({ showToolbar: false });The toolbar commands are exposed independently of the bundled DOM toolbar. This makes it possible to render them with any UI framework or component system.
import {
getLanguage,
isToolbarButton,
scopeAt,
toolbarEntries
} from 'codemirror-visual-markup';
function renderToolbar(host, view, languageId) {
const language = getLanguage(languageId);
const scope = scopeAt(
view.state,
view.state.selection.main.head,
language
);
host.replaceChildren();
for (const entry of toolbarEntries(language, scope)) {
if (!isToolbarButton(entry)) continue;
const button = document.createElement('button');
button.textContent = entry.label;
button.addEventListener('click', () => entry.command(view));
host.appendChild(button);
}
}Recompute the entries when the selection changes so context-sensitive table controls appear only when relevant.
The exported helpers wrapSelection, insertText, insertBlock, createWrapItem, createHeadingItem, createListItem, createTableItem, and createColorItem can also be used to build a toolbar from scratch.
| Shortcut | Action |
|---|---|
Ctrl/Cmd + E |
Toggle source and visual mode |
Ctrl/Cmd + Shift + C |
Show or conceal source syntax in visual mode |
Ctrl/Cmd + Shift + M |
Toggle source-mode math hover |
Ctrl/Cmd + Shift + T |
Toggle the bundled toolbar |
Placing the cursor inside a visual construct reveals its source syntax, so the underlying document remains directly editable without leaving visual mode.
Languages can be registered with a tokenizer rule set, style mapping, and command definitions:
import {
registerLanguage,
type Language
} from 'codemirror-visual-markup';
const language: Language = {
id: 'example',
name: 'Example',
rules: [headingRule, emphasisRule],
style(token) {
if (token.kind === 'heading') {
return {
class: `cm-lv-h${token.level}`,
block: true
};
}
return null;
},
commands: {
wrap: {
bold: ['**', '**']
},
heading(level, text) {
return `${'#'.repeat(level)} ${text}`;
},
list(_kind, items) {
return items.map(item => `- ${item}`).join('\n');
},
table(rows, cols) {
return `${rows} x ${cols}`;
},
color(_kind, _color, text) {
return text;
}
}
};
registerLanguage(language);Optional table and figure adapters can provide richer visual structure for languages that support them.
git clone https://github.com/TeXlyre/codemirror-visual-markup.git
cd codemirror-visual-markup
npm install
npm run buildRun the tests with:
npm testRun the GitHub Pages example locally with:
npm run pages-exampleMIT License. See LICENSE for details.