import "capsomer/tokens.css";
import "capsomer/markdown-editor.css";
import { MarkdownEditor } from "capsomer/react/markdown-editor";
Usage
<div class="cap-md cap-field" data-cap="markdown-editor">
<label class="cap-field-label" for="body">Body</label>
<p class="cap-field-help" id="body-h">Markdown. Ctrl or Cmd + K links to a page.</p>
<textarea class="cap-input cap-md-source" id="body" name="body" aria-describedby="body-h" spellcheck="true">## Why the checks moved to the edge
The monitors now run from three regions.</textarea>
</div>
import { enhance, getMarkdownEditor } from "capsomer/behavior/markdown-editor";
enhance(document, {
linkTargets: [{ href: "/writing/first-incident", title: "The first incident write-up" }],
scaffolds: [
{ id: "figure", label: "Figure", hint: "An image with a caption", icon: "M3 4h18v13H3zM3 14l4-4 5 5M6 21h12",
text: ':::figure{src="" alt=""}\nA caption.\n:::', cursorAfter: 'src="' },
],
// image is { alt, decorative }: send both, so the file is stored described.
onUpload: async (file, image, signal) => ({ url: await sendToBucket(file, image, signal) }),
imageMarkdown: ({ url, alt }) => `:::figure{src="${url}" alt="${alt}"}\n:::`,
onSave: (value) => saveDraft(value),
});
<MarkdownEditor
label="Body"
name="body"
value={body}
onChange={setBody}
onSave={save}
help="Markdown. Ctrl or Cmd + K links to a page."
error={errors.body}
linkTargets={posts.map((p) => ({ href: `/writing/${p.slug}`, title: p.title, note: p.live ? undefined : "not live yet (draft)" }))}
scaffolds={scaffolds}
onUpload={async (file, image, signal) => ({ url: await sendToBucket(file, image, signal) })}
/>
API reference
MarkdownEditor
Prop
Type
Required
Does
label
ReactNode
Yes
The visible label above the editor.
ariaLabel
string
The surface's accessible name; defaults to the label's text plus ", markdown".
name
string
The field's name in a form: the markdown is posted in a hidden textarea of this name.
id
string
value
string
Controlled: the text. Without it the editor keeps its own, starting at defaultValue.
defaultValue
string
onChange
(value: string) => void
placeholder
string
readOnly
boolean
disabled
boolean
required
boolean
maxLength
number
A hint, not a stop: the footer counts characters against it and says when the text is over.
help
ReactNode
Help, between the label and the editor, read as its description.
error
ReactNode
What is wrong and what to do; shown below the editor, and marks it invalid.
onReady
(handle: MarkdownEditorHandle) => void
Called once with the handle when CodeMirror has loaded.
nonce
string
The CSP nonce for the styles CodeMirror injects. Defaults to the nonce on the page's first script that has one.
Uploads a pasted, dropped or chosen image once the person has described it, and says where it went. The signal aborts when they cancel while it is on its way. Without it, the image button, the drop hint and the describe step are absent.
Upgrades one editor: the element carrying data-cap="markdown-editor", holding a label and a textarea. Resolves once CodeMirror has loaded and the surface is mounted; if it cannot load, the textarea simply stays, and the promise rejects.
getMarkdownEditor
(host: Element): MarkdownEditorHandle | undefined
The handle of an editor that has finished loading, or undefined while it is still the plain textarea (listen for the bubbling cap-md-ready event to know when).
Upgrades every [data-cap="markdown-editor"] under root not yet upgraded. The textarea is the editor until CodeMirror has loaded, and again if it cannot. options apply to each one; to give editors different options, pass a narrower root. Returns a function that undoes it.
CSS variables
Variable
Default
--cap-md-min
16rem
Parts and data attributes
Class
Is
.cap-md
the root
.cap-md-foot
a part
.cap-md-frame
a part
.cap-md-hint
a part
.cap-md-limit
a part
.cap-md-option-hint
a part
.cap-md-option-note
a part
.cap-md-palette
a part
.cap-md-palette-label
a part
.cap-md-palette-note
a part
.cap-md-sep
a part
.cap-md-slash
a part
.cap-md-slash-hint
a part
.cap-md-slash-item
a part
.cap-md-source
a part
.cap-md-stats
a part
.cap-md-surface
a part
.cap-md-tool
a part
.cap-md-toolbar
a part
.cap-md-toolbar-hint
a part
.cap-md-upload
a part
.cap-md-upload-actions
a part
.cap-md-upload-error
a part
.cap-md-upload-fields
a part
.cap-md-upload-thumb
a part
.cap-md-upload-wait
a part
Attribute
Values
data-active
present or absent
data-over
present or absent
State
Read from
:active
the platform
:disabled
the platform
:empty
the platform
:focus-visible
the platform
:hover
the platform
[aria-disabled="true"]
an attribute
[aria-invalid="true"]
an attribute
[aria-readonly="true"]
an attribute
Accessibility
Key
Does
Tab
Enters the toolbar at its one stop; the next Tab enters the surface; Tab in the surface leaves it
Left arrow, Right arrow, Home, End
Moves between the toolbar's buttons, wrapping
Ctrl or Cmd B, I, E
Bold, italic or code around the selection; with none, the cursor lands between the marks
Ctrl or Cmd K
Opens the link palette, the selection as its query
Down arrow, Up arrow (palette)
Moves the active option, wrapping
Enter (palette)
Links the active option, or the typed address; the cursor lands after the link
/ alone on a line
Opens the block menu (when the app supplies blocks)
Down arrow (surface, menu open)
Enters the block menu
Up arrow, Down arrow, Home, End (block menu)
Moves between blocks, wrapping
Enter (block menu)
Replaces the / with the block, the cursor where the block says
Esc
Closes the link palette or the block menu and returns to the text; with neither open it is not claimed
Ctrl or Cmd S
Calls onSave and fires cap-md-save; focus stays in the editor
Ctrl or Cmd Z, Ctrl or Cmd Y
Undo, redo
Enter (alt field), Esc
Inserts the image once it has alt text; Esc discards it and returns to the text
The surface is a textbox that is multiline, named "Label, markdown", described by the field's help and error, and carries aria-required, aria-invalid, aria-readonly and aria-disabled from the textarea.
The toolbar is a toolbar named "Markdown formatting"; the link palette is a group holding a combobox named "Link to" with aria-activedescendant over a listbox; the block menu is a named list of buttons.
The upload step is a group named "Describe the image", aria-busy while uploading; its progress and result are said in a status region, a failure in an alert.
Single-key shortcuts of other components (j, k, /, z) never act inside the editor: the surface is editable text, which the shortcuts registry treats as typing. The slash menu is typed text, not a shortcut, so data-cap-single-keys="off" does not change it; Ctrl or Cmd keys are modifiers, not single keys.
Hit areas are at least --target; the toolbar's buttons grow with the density.
Forced colors: the focus ring, the active option and the focused block keep an outline; an invalid frame gets a thicker edge.
Under a strict style-src, pass the CSP nonce (nonce), or the page's first <script nonce> is read; without it CodeMirror's injected styles are dropped.