Gravity UI Markdown Editor

The @gravity-ui/markdown-editor package provides a cm submodule that re-exports several core CodeMirror modules. This allows you to use CodeMirror functionality (like state management, view handling, and language support) without needing to install the individual @codemirror/* packages separately in your project.

Supported re-exports include:

• @codemirror/autocomplete
• @codemirror/commands
• @codemirror/language
• @codemirror/state
• @codemirror/view

import {EditorView} from '@gravity-ui/markdown-editor/cm/view';

The Markdown Editor operates in two modes which serve different purposes during extension development:

1. Markup Mode: The editor performs standard conversion of markdown (or advanced markdown like YFM) into HTML. Use this mode to verify that your markdown plugin correctly translates syntax into the expected HTML code.
2. WYSIWYG Mode: This is where editor extensions actually live. Extensions enhance the visual, interactive functionality of the editor.

When developing, ensure your markdown plugin works in Markup mode first, then implement the corresponding extension for the WYSIWYG functionality.

When writing tests for the editor's view layer and plugins in WYSIWYG mode, follow these guidelines:

Input Emulation

Use editor.fill, editor.press, or editor.pressSequentially to emulate user input within the contenteditable region.

Locators

• React-based components: Prefer locating elements via data-qa attributes (especially for plugins defining node views via React).
• Non-React elements: For elements rendered via toDOM in a ProseMirror node spec, use class names or specific attributes.

Click Testing

Choose the appropriate method based on your needs:

• locator.click()
• element.dispatchEvent('click', params) (Use { bubbles: true } for events involving bubbling)
• page.mouse.click(x, y)

Clipboard

Note that Playwright clipboard support varies across browsers; account for this when testing copy-paste functionality.

Context-specific toolbar components are UI elements that depend on specific editor extensions to function correctly. Because their operation is tied to the presence of these extensions, they cannot be added directly to the standard MenuBar component. Instead, they are intended to be used in contexts where the required extensions are active.

Examples of such components include:

• Heading selection buttons
• Text coloring buttons
• List formatting buttons

The editor supports six distinct toolbar contexts:

1. Visible toolbar in WYSIWYG mode.
2. "Three-dots" menu in WYSIWYG mode.
3. Visible toolbar in Markdown mode.
4. "Three-dots" menu in Markdown mode.
5. Selection-based toolbar in WYSIWYG (appears when text is selected).
6. Slash-triggered toolbar in WYSIWYG (appears when typing /).

Use this editor when:

• You need a dual-mode editor that switches between WYSIWYG (ProseMirror) and raw markup (CodeMirror).
• You are working with Markdown or YFM (YAML Front Matter) syntax.
• You require an extensible editor (e.g., adding LaTeX, Mermaid, HTML, or GPT extensions).

Do NOT use this editor when:

• Read-only rendering: If you only need to render Markdown to HTML without editing, use @diplodoc/transform instead.
• Plain text input: For simple multiline text, use TextArea from @gravity-ui/uikit.
• Non-Markdown rich text: This editor is specifically optimized for Markdown/YFM.

When reference screenshots need to be updated, use the following commands (ideally within the Docker environment):

• Update all snapshots: pnpm run playwright:docker:update
• Update snapshots for a specific test (using --grep or -g): pnpm run playwright:docker:update --grep 'test name'
• Update only snapshots that failed in the last run: pnpm run playwright:docker:update --last-failed

Always run tests in Docker to match CI results. You can run tests from either the monorepo root or the demo/ subpackage.

From the monorepo root

• Run all tests: pnpm run test:e2e
• Display report: pnpm run test:e2e:report
• Filter by test name: pnpm run test:e2e --grep '<name>'

From the demo/ subpackage

• Run all tests: pnpm run playwright:docker
• Clear cache: pnpm run playwright:docker:clear
• Display report: pnpm run playwright:docker:report
• Filter by test name: pnpm run playwright:docker --grep '<name>'

# From root
pnpm run test:e2e

# From demo/
pnpm run playwright:docker

Pass the configured plugins array (containing the LaTeX transformer) into the MarkdownEditor constructor configuration.

const editor = new MarkdownEditor({
  // Editor configuration
  plugins,
  // Other configurations,
});