Markdown editor

Markdown editor in Storybook

Usage

Overview

The markdown editor is an editor that enables users to author content using markdown syntax. It provides a live-formatted preview of the text as it is typed, eliminating the need for a separate split-screen view. The editor includes a toolbar for common text styling, including headings, emphasis, lists, and links.

When to use

• For structured, long-form content that requires hierarchical organization, such as reports, detailed notes, or multi-section descriptions.
• When users need to create a mix of text styles, including multiple heading levels (H1-H6), bold and italic emphasis, and complex lists.
• To provide an intuitive editing interface where users can either use standard keyboard shortcuts or the toolbar to format their content.

When not to use

• For short, single-line data that doesn't require formatting. Use a standard text input component instead.
• When the workflow requires advanced table creation or embedding complex media like videos or interactive widgets.
• For writing code that requires multi-language syntax highlighting or line numbering.

Formatting

Anatomy

The markdown editor component consists of the following elements:

1. Toolbar: A container for formatting actions that remains visible while the user is in edit mode.
2. Undo and redo: Buttons that enable users to reverse or re-apply recent changes.
3. Bold and italic: Buttons used to apply emphasis (italic) or strong emphasis (bold) to text.
4. Text style menu: A dropdown menu to switch between normal text and six levels of headings.
5. Link: A tool used to insert and manage hyperlinks within the content.
6. List toggles: Buttons to create bulleted (unordered) or numbered (ordered) lists.
7. Indentation tools: Buttons to increase or decrease the indent level of text.
8. Tooltips: Brief text labels that appear on hover to identify the function of each toolbar button.
9. Editing area: The interactive area where text is entered and rendered with live formatting.

Behaviors

Live formatting

The markdown editor allows users to format text using either the toolbar or markdown syntax directly. When a user types markdown syntax, such as ** to bold a word, the component automatically converts it into visual formatting. This enables users to focus on the content's appearance without managing raw code.

Read-only mode

When the readOnly prop is set to true, the component functions as a content viewer. In this state:

• The toolbar is hidden.
• The text cannot be edited.
• The content remains formatted according to the markdown provided in the value prop.

AI-generated summaries

The markdown editor is designed to support workflows where content is generated outside the UI, such as underwriting summaries returned by AI services (for example, Merlin).

• Automatic formatting: When the editor receives markdown-formatted content, it renders headings, lists, and emphasis with the correct visual hierarchy.
• Content review and refinement: Underwriters can review the pre-formatted summary and use the toolbar or keyboard shortcuts to add notes, adjust emphasis, or correct structure.
• Editable vs. read-only: Depending on the workflow, teams can present these summaries as editable for refinement or read-only for final review.

History and operations

The editor tracks changes made during the current session, allowing users to manage their editing history:

• Undo and redo: Users can reverse recent formatting or text changes using the toolbar buttons or standard keyboard shortcuts (Ctrl+Z and Ctrl+Y).
• Copy and paste: The editor supports standard clipboard operations, maintaining basic formatting when content is moved into or out of the editing area.
• Toolbar tooltips: To assist with icon identification, tooltips appear on hover for all toolbar buttons.

Nested list indentation

The editor supports a deep hierarchy for organized content, allowing for up to six levels of indentation.

• Ordered list patterns: When nesting numbered lists, the markers follow a repeating cycle of numbers, lowercase letters, and lowercase Roman numerals to help users distinguish between levels.
• Unordered list consistency: Bulleted lists use different markers at different levels, following a repeating cycle of discs, circles, and squares.

Content

General writing guidelines

• En todos los aspectos del diseño de las interfaces de productos de Guidewire, utilice mayúsculas como se usan en las oraciones. No use mayúsculas en todas las palabras.
• Use verbos en tiempo presente y voz activa en la mayoría de las situaciones.
• Use contracciones comunes para darle al texto un tono más natural e informal (pauta correspondiente al inglés).
• Use un lenguaje sencillo. Evite la jerga innecesaria y el lenguaje complejo.
• Las palabras y las oraciones deben ser breves.

The markdown editor follows the same typographic principles as other Jutro components. For rules on maintaining a purposeful hierarchy and using approved font variations, see the foundational typography guidelines.

Markdown editor writing guidelines

• Use descriptive placeholders: Provide a hint that describes the expected content, such as "Enter a detailed description of the risk".
• Structure for readability: Use headings and lists to break up long blocks of text and create a clear hierarchy.

Accessibility

The markdown editor is designed to meet WCAG 2.1 AA accessibility guidelines.

• Keyboard navigation: All formatting actions are accessible using the toolbar or through standard keyboard shortcuts, such as Ctrl+B for bold and Ctrl+I for italics.
• Screen reader support: The component uses specific translation keys (for example, textStyleHeading1, linkTextLabel) to provide accessible ARIA labels for toolbar buttons and menus.
• Visual focus indicators: Interactive elements within the toolbar, such as buttons and dropdown menus, display a high-contrast blue outline when receiving keyboard focus.
• Visual labeling: Toolbar tooltips provide a persistent visual text label on hover, ensuring the function of each icon is clear to users who might not recognize the symbol alone.
• Semantic HTML: The editor automatically generates semantically correct HTML tags (such as <h1> through <h6>, <ul>, and <ol>), allowing assistive technology to accurately parse the document structure.

Code

<MarkdownEditor />

Import statement

import { MarkdownEditor } from '@jutro/experimental-markdown';

Component contract

Asegúrese de comprender la superficie de la API de componentes del sistema de diseño, así como sus implicaciones, ventajas y desventajas. Obtenga más información en nuestra introducción a la API de componentes.

Properties

emptyStateText

Tipo

IntlMessageShape

Descripción

The text that appears when the editor is empty in read-only mode.

onChange

Tipo

(markdown: string) => void

Descripción

The callback that runs when the editor content changes. Receives the updated markdown string as an argument.

placeholder

Tipo

IntlMessageShape

Descripción

The placeholder text that appears when the editor is empty. Supports internationalization using IntlMessageShape.

readOnly

Tipo

boolean

Descripción

When set to true, the editor is in read-only mode. In this mode, the toolbar is hidden and the content cannot be edited.

value

Tipo

string

Descripción

The Markdown content to display in the editor.

Hooks

No hay ganchos para markdown editor.

Translation keys

Key	Used for
jutro-experimental-markdown.MarkdownEditor.editorAriaLabel	aria-label value for the Markdown editor.
jutro-experimental-markdown.MarkdownEditor.defaultPlaceholder	Default placeholder text.
jutro-experimental-markdown.MarkdownEditor.defaultEmptyStateText	Default empty state text.
jutro-experimental-markdown.MarkdownEditor.boldButton	aria-label value for the bold button.
jutro-experimental-markdown.MarkdownEditor.italicButton	aria-label value for the italic button.
jutro-experimental-markdown.MarkdownEditor.bulletListButton	aria-label value for the bullet list button.
jutro-experimental-markdown.MarkdownEditor.numberedListButton	aria-label value for the numbered list button.
jutro-experimental-markdown.MarkdownEditor.toolbarAriaLabel	aria-label value for the toolbar.
jutro-experimental-markdown.MarkdownEditor.textStyleButton	aria-label value for the text style button.
jutro-experimental-markdown.MarkdownEditor.textStyleNormal	aria-label value for the button to set text style to normal.
jutro-experimental-markdown.MarkdownEditor.textStyleHeading1	aria-label value for the button to set text style to level 1 heading.
jutro-experimental-markdown.MarkdownEditor.textStyleHeading2	aria-label value for the button to set text style to level 2 heading.
jutro-experimental-markdown.MarkdownEditor.textStyleHeading3	aria-label value for the button to set text style to level 3 heading.
jutro-experimental-markdown.MarkdownEditor.textStyleHeading4	aria-label value for the button to set text style to level 4 heading.
jutro-experimental-markdown.MarkdownEditor.textStyleHeading5	aria-label value for the button to set text style to level 5 heading.
jutro-experimental-markdown.MarkdownEditor.textStyleHeading6	aria-label value for the button to set text style to level 6 heading.
jutro-experimental-markdown.MarkdownEditor.indentIncreaseButton	aria-label value for the increase indent button.
jutro-experimental-markdown.MarkdownEditor.indentDecreaseButton	aria-label value for the decrease indent button.
jutro-experimental-markdown.MarkdownEditor.linkButton	aria-label value for the hyperlink button.
jutro-experimental-markdown.MarkdownEditor.linkTextLabel	aria-label value for the text box used to set the display text of a hyperlink in the insert link modal.
jutro-experimental-markdown.MarkdownEditor.linkUrlLabel	aria-label value for the text box to set the URL of a hyperlink in the insert link modal.
jutro-experimental-markdown.MarkdownEditor.linkInsertButton	aria-label value for the insert link button in the insert link modal.
jutro-experimental-markdown.MarkdownEditor.linkCancelButton	aria-label value for the cancel button in the insert link modal.
jutro-experimental-markdown.MarkdownEditor.linkUrlPlaceholder	Placeholder text for the text box to set the URL of a hyperlink in the insert link modal.
jutro-experimental-markdown.MarkdownEditor.linkTextPlaceholder	Placeholder text for the text box to set the display text of a hyperlink in the insert link modal.
jutro-experimental-markdown.MarkdownEditor.linkUrlError	Error message displayed when the link URL is invalid.
jutro-experimental-markdown.MarkdownEditor.linkUrlRequired	Error message displayed when the link URL is empty.
jutro-experimental-markdown.MarkdownEditor.undoButton	aria-label value for the undo button.
jutro-experimental-markdown.MarkdownEditor.redoButton	aria-label value for the redo button.

Escape hatches

Para obtener más información, consulte nuestra documentación sobre escotillas de escape.

Examples

Check out the Usage section for details about how to design a markdown editor properly, and the different configuration options available.

Basic markdown editor example

A markdown editor is a text box that allows users to enter text with markdown formatting. Users can either use the toolbar to set formatting, or use markdown syntax directly. When users enter markdown syntax directly, the text updates live as they edit it.

<MarkdownEditor />

Read-only markdown editor example

A markdown editor can be set to read-only when the readOnly prop is set to true. In this state, the toolbar is not shown and the text cannot be edited.

const CONTENT = `
# MD Heading 1

This is **markdown** text that has been *written* using markdown syntax.

Read the [Markdown Guide](https://www.markdownguide.org) to learn more!
`;

<JutroWrapper center>
  <MarkdownEditor
    readOnly
    value={CONTENT}
  />
</JutroWrapper>;

Controlled markdown editor example

You can use React states to control a markdown editor. The following example renders a markdown editor that demonstrates state management and programmatic control. The sections that relate directly to the markdown component's interaction with react states are highlighted.

import React, { useState } from 'react';
import { MarkdownEditor } from '@jutro/experimental-markdown';
import {
  ActionCardHeader,
  ActionCardContent,
  ActionCard,
} from '@jutro/experimental-cards';
import { Button } from '@jutro/components';

const CONTENT = `
# MD Heading 1

This is **markdown** text that has been *written* using markdown syntax.

Read the [Markdown Guide](https://www.markdownguide.org) to learn more!
`;

const CONTROLLED_CONTENT =
  'Edit this text and watch the formatting update in real-time.';

export function MarkdownEditorControlled() {
  const [value, setValue] = useState(CONTROLLED_CONTENT);
  const [readOnly, setReadOnly] = useState(false);
  const [showSource, setShowSource] = useState(false);

  const handleClear = () => setValue('');
  const handleLoadSample = () => setValue(CONTENT);

  return (
    <ActionCard initialExpanded>
      <ActionCardHeader
        title="Controlled Editor"
        subtitle="Demonstration of state management and programmatic control"
      />
      <ActionCardContent>
        <div
          style={{
            display: 'flex',
            gap: '8px',
            alignItems: 'center',
            flexWrap: 'wrap',
            marginBottom: '16px',
          }}>
          <Button
            label="Load Sample"
            onClick={handleLoadSample}
            variant="secondary"
            size="small"
          />
          <Button
            label="Clear"
            onClick={handleClear}
            variant="secondary"
            size="small"
          />
          <Button
            label={showSource ? 'Hide Source' : 'Show Source'}
            onClick={() => setShowSource(!showSource)}
            variant="secondary"
            size="small"
          />
          <Button
            label={readOnly ? 'Enable Editing' : 'Make Read-Only'}
            onClick={() => setReadOnly(!readOnly)}
            variant="secondary"
            size="small"
          />
        </div>

        <MarkdownEditor
          value={value}
          onChange={setValue}
          readOnly={readOnly}
        />

        {showSource && (
          <div
            style={{
              marginTop: '16px',
              padding: '16px',
              background: '#f5f5f5',
              borderRadius: '4px',
              border: '1px solid #e0e0e0',
            }}>
            <div
              style={{
                fontSize: '12px',
                fontWeight: 600,
                marginBottom: '8px',
                color: '#666',
              }}>
              MARKDOWN SOURCE
            </div>
            <pre
              style={{
                margin: 0,
                padding: '12px',
                background: 'white',
                borderRadius: '4px',
                fontSize: '13px',
                fontFamily: 'monospace',
                overflow: 'auto',
                maxHeight: '200px',
              }}>
              {value || '(empty)'}
            </pre>
          </div>
        )}
      </ActionCardContent>
    </ActionCard>
  );
}

Changelog

10-12-x-iteration-2

Undo button and redo button added to the markdown editor component.

10-12-x-iteration-1

MarkdownEditor component added.