API Reference

---

new TravenEditor(options)

Initializes a new editor instance.

Options

Option	Type	Default	Description
element	HTMLElement	(Required)	The DOM element inside which the WYSIWYM editor will mount.
sourceElement	HTMLElement	null	Optional DOM element to mount the secondary raw editor for live sync.
initialValue	string	""	The starting Markdown document string.
lineNumbers	boolean	false	Show line numbers and folding gutters in the primary editor.
sourceLineNumbers	boolean	false	Show line numbers and gutters in the raw sync editor.
lineWrapping	boolean	true	Enable soft line wrapping in the primary editor.
sourceLineWrapping	boolean	true	Enable soft line wrapping in the raw sync editor.
onChange	function	null	Callback fired on change: (value: string) => void.
onSave	function	null	Callback fired on Save command (Cmd+S / Ctrl+S): (value: string) => void.
onUploadImage	function	null	Callback returning a promise of the uploaded image's URL: (file: File) => Promise<string>.
onStatsUpdate	function	null	Callback fired when document stats change: (stats: { words: number, characters: number, readTime: number }) => void.
theme	"light" | "dark"	"light"	Configures baseline cursor theme variables and dark mode class triggers.
caretColor	string	""	Custom hex color for the editor caret overrides.
toolbar	Array<string> | boolean	false	A list of tool key strings defining the toolbar buttons layout, or false to disable the toolbar.
vimMode	boolean	false	Enables Vim keybindings and normal mode emulation in both editing panes.
readOnly	boolean	false	Enables read-only mode for both primary and secondary editor panes.
keybindings	object	{}	Key-value pairs overriding default tool keybindings (e.g. { bold: "Ctrl-Shift-b" }).
katex	boolean | string | object	false	Configures KaTeX loading. If false (default), only uses local preloaded window.katex. If true, loads from JSDelivr CDN. If a string or object, defines custom self-hosted paths (e.g. { js: "path/to/katex.js", css: "path/to/katex.css" }).
components	Array<string | object>	(Default presets)	Pre-defined custom component schemas.
componentsUrl	string | boolean	"assets/components.json"	Path/URL to load custom component schemas, or false to disable.
toolbarMode	"static" | "floating" | "hybrid"	"static"	Presentation layout mode for the toolbar.
bubbleHotkey	string	"Mod-."	Keyboard hotkey to open the selection bubble.
gutterHotkey	string	"Mod-Shift-Enter"	Keyboard hotkey to open the gutter plus menu.
bubbleAppearDelay	number	200	Delay in ms between selection and selection bubble appearance.
autoLoadStyles	boolean	true	Auto-inject core CSS from CDN/local bundle. Set to false for strict CSP environments.
codeLanguages	Array	null	CodeMirror LanguageDescription array to enable syntax highlighting in fenced code blocks.

---

Public Methods

getValue()

Returns the complete document content as a Markdown string.

• Returns: string

setValue(value)

Replaces the entire document content with a new Markdown string.

• Parameters: value (string)

focus()

Programmatically focuses the primary editor view.

setReadOnly(readOnly)

Sets the editor to read-only or read-write mode dynamically.

• Parameters: readOnly (boolean): Whether the editor should be read-only.

isReadOnly()

Returns whether the editor is currently in read-only mode.

• Returns: boolean

getSelection()

Returns the currently selected text in the primary editor.

• Returns: string

setSelection(anchor, head)

Sets the selection range in the editor and focuses it.

• Parameters:
  • anchor (number): The starting character index of the selection.
  • head (number, optional): The ending character index of the selection. Defaults to anchor.

insertSnippet(before, after, placeholder)

Wraps the current text selection with markdown characters. If no text is selected, inserts a formatted placeholder string.

• Parameters:
  • before (string): Prefix tags (e.g. **).
  • after (string): Suffix tags (e.g. **).
  • placeholder (string): Text displayed inside tags if selection is empty.

undo()

Triggers history undo on the currently focused editor (WYSIWYM or raw).

redo()

Triggers history redo on the currently focused editor (WYSIWYM or raw).

setTheme(theme)

Dynamically toggles light or dark mode styling across the editors.

• Parameters: theme ("light" | "dark")

setVimMode(enabled)

Dynamically toggles Vim mode emulation at runtime.

• Parameters: enabled (boolean)

getCharacterCount()

Returns the total character length of the active document.

• Returns: number

getWordCount()

Returns the total word count of the active document.

• Returns: number

getReadTime()

Returns the estimated reading time of the active document in minutes.

• Returns: number

registerRenderer(renderFn)

Registers a custom Markdown compilation function to render custom HTML previews.

• Parameters: renderFn ((markdown: string) => string)

getContentHtml()

Returns the compiled HTML representation of the document, using the registered custom renderer or the built-in fallback parser.

• Returns: string

getView()

Exposes the primary CodeMirror EditorView instance.

• Returns: EditorView

triggerSave()

Programmatically invokes the registered save callback with current values.

on(event, callback)

Registers an event listener callback.

• Parameters:
  • event ("change" | "save" | "statsUpdate"): The event name.
  • callback (function): The callback function:
    • For "change" / "save": receives (value: string) (the updated Markdown document).
    • For "statsUpdate": receives a stats object: { words: number, characters: number, readTime: number }.

Example:

editor.on("statsUpdate", (stats) => {
  console.log(`Words: ${stats.words}, Characters: ${stats.characters}, Read Time: ${stats.readTime} min`);
});

getUploadHandler()

Returns the configured image upload handler, or null if not configured.

• Returns: (file: File) => Promise<string> or null

getComponents()

Returns the list of currently registered component schemas.

• Returns: Array<string | object>

destroy()

Cleans up event listeners and destroys CodeMirror instances.

---

Editing & Formatting Helpers

Traven exposes several built-in commands to manipulate text selections programmatically:

clear()

Wipes the entire document content and focuses the primary editor.

toUpperCase()

Converts the active selection to uppercase, preserving the selected text boundary.

toLowerCase()

Converts the active selection to lowercase, preserving the selected text boundary.

capitalizeWords()

Capitalizes the first letter of every word in the active selection.

removeFormatting()

Strips all inline styles (bold, italic, code backticks, strikethrough, highlights) and block formatting (lists, taskboxes, headings, blockquotes, horizontal rules) from the selection.

toggleFullscreen()

Toggles fullscreen class .is-fullscreen on the editor's parent container and recalculates layout coordinates.

openSearch()

Opens the built-in CodeMirror find-and-replace search panel.

goToLine(lineNumber)

Navigates the cursor to the specified 1-indexed line number and scrolls it into view.

• Parameters: lineNumber (number)

insertCodeBlock()

Wraps the selection in a fenced code block (```) with appropriate line spacing.

insertHR()

Inserts a standalone markdown horizontal rule line (---) at the cursor.

insertTable()

Inserts a pre-formatted 3x3 Markdown table template at the cursor, and selects the first header text.

setHeading(level)

Toggles or applies a heading level (1 to 6) prefix to the active line. Pass 0 to strip headings.

• Parameters: level (number)

insertBlockquote()

Converts the active selection or line into a markdown blockquote block (> ).

insertDateTime()

Inserts the current date and time string at the cursor.

insertList(type)

Converts the active selection or line into a list of the specified type.

• Parameters: type ("ul" | "ol" | "task")

---

Static Methods

TravenEditor.configureMermaid(options)

Configures Mermaid diagram loading globally.

• Parameters:
  • options (boolean | string | object):
    • true: Enable Mermaid loading from standard CDN (v11.4.0).
    • string: Enable with a custom CDN script URL.
    • object: Configuration object containing optional js URL property.
    • false: Disable Mermaid.

TravenEditor.initMermaid(container)

Scans the specified container element and renders any uninitialized Mermaid diagrams.

• Parameters:
  • container (HTMLElement): The DOM container element to scan.
• Returns: Promise<void>