Usage

This page covers the basic API for embedding ToastWrite in a web page.

Minimal example

HTML:

<div id="editor-root"></div>
<div id="viewer-root"></div>

JavaScript:

import { Editor, Viewer } from '@toastwrite/editor';
import '@toastwrite/editor/style.css';

const editorRoot = document.querySelector('#editor-root') as HTMLElement;
const viewerRoot = document.querySelector('#viewer-root') as HTMLElement;

const viewer = new Viewer({
  el: viewerRoot,
  initialValue: '# Hello\n\nStart writing **Markdown**.',
  height: '400px',
});

const editor = new Editor({
  el: editorRoot,
  initialValue: '# Hello\n\nStart writing **Markdown**.',
  height: '400px',
  previewStyle: 'vertical',
  previewSplitter: true,
  events: {
    change: () => {
      viewer.setMarkdown(editor.getMarkdown());
    },
  },
});

Factory helper

Use Editor.factory to create either an editor or viewer from one options object:

import Editor from '@toastwrite/editor';

const editor = Editor.factory({
  el: document.querySelector('#root')!,
  viewer: false, // set to true for Viewer
});

Editor options

Option	Type	Default	Description
el	HTMLElement	—	Required. Container element
initialValue	string	''	Initial Markdown content
height	string	'300px'	Editor height
minHeight	string	'200px'	Minimum height
placeholder	string	''	Placeholder text
previewStyle	'tab' | 'vertical'	'vertical'	Preview layout
previewSplitter	boolean	false	Draggable split between editor and preview
scrollSync	boolean	true	Sync scroll between editor and preview
hideToolbar	boolean	false	Hide the formatting toolbar
toolbarItems	CommandId[]	all built-ins	Customize toolbar buttons
theme	'light' | 'dark'	'light'	Color theme
frontMatter	boolean	false	Parse YAML/TOML/JSON front matter
referenceDefinition	boolean	false	Enable reference-style links
plugins	EditorPlugin[]	[]	Editor plugins
events	object	—	Event handlers (see below)
beforePreviewRender	(html) => html	—	Hook to transform preview HTML

Viewer options

The viewer accepts the same base options as the editor, except preview-related settings (previewStyle, hideToolbar, etc.) are not used.

Public API

Editor

Method	Description
getMarkdown()	Get current Markdown source
setMarkdown(markdown, cursorToEnd?)	Replace content
getHTML()	Get rendered preview HTML
getSelection() / setSelection()	Get or set cursor/selection range
executeCommand(commandId)	Run a toolbar command programmatically
on(event, handler) / off(event, handler)	Subscribe to events
destroy()	Tear down the instance

Viewer

Method	Description
getMarkdown()	Get current Markdown source
setMarkdown(markdown)	Replace content and re-render
on(event, handler) / off(event, handler)	Subscribe to events
destroy()	Tear down the instance

Events

Event	Payload	Description
load	—	Fired when the instance is ready
change	—	Content changed
focus / blur	—	Focus state changed
caretChange	—	Selection/caret moved
beforePreviewRender	string (HTML)	Before preview HTML is applied

Toolbar commands

Built-in toolbar commands include bold, italic, strikethrough, headings, lists, task lists, blockquotes, horizontal rules, links, tables, inline code, and code blocks. Keyboard shortcuts are available for most commands (for example Mod-b for bold, Mod-Shift-k for links).

Customize the toolbar with toolbarItems:

new Editor({
  el: root,
  toolbarItems: ['bold', 'italic', 'link', 'codeBlock'],
});

Enable front matter and reference links

new Editor({
  el: root,
  frontMatter: true,
  referenceDefinition: true,
  initialValue: `---
title: My Document
---

[link][ref]

[ref]: https://example.com
`,
});

See Front Matter and Reference Definitions for syntax details.

Cleanup

Always call destroy() when removing the editor from the DOM (for example in a SPA route change):

editor.destroy();
viewer.destroy();

Learn more

Browse Markdown Syntax for every supported construct and how to write it.