Formats and editing policy

Documentation index

Supported storage/view combinations

JavaScript format C# enum Source Visual Intended use
markdown EditorFormat.Markdown Yes Yes Notes and authored Markdown
html EditorFormat.Html Yes Yes Supported HTML fragments
text EditorFormat.PlainText Yes No SQL, JavaScript, plain text
rich-json EditorFormat.RichJson No Yes Legacy/internal rich document serialization

HTML storage represents a fragment, not an arbitrary full website with scripts, stylesheets, forms, or application behavior. Rich JSON is not the preferred public interchange format for ordinary application content; its schema is tied to the model implementation.

The default JavaScript view is Source. The default WinForms view is Visual. Both default to Markdown storage and Markdown language. Specify all three values explicitly at host boundaries to avoid relying on that difference.

Markdown capabilities

The built-in codec handles a conservative subset: paragraphs; ATX headings; emphasis/strong/strike/inline code; links; lists/tasks; quotes; fenced and indented code; thematic breaks; rectangular pipe tables; and image references. It has source-preservation support and structured list/table parsing, but is not a full CommonMark or GFM implementation. Reference-style syntax, complex nesting combinations, and arbitrary HTML may be represented as opaque raw content rather than editable structures.

Markdown with embedded HTML allows a small rich-style extension for underline, curated fonts, colors, and sizes. Setting allowEmbeddedHtml: false / AllowEmbeddedHtml = false removes those options from Markdown editing. It does not mean that every possible Markdown construct is recognized.

Presets and feature overrides

Preset Enabled features before format restrictions
plain / Plain None of the rich feature flags
basic / Basic Bold, italic, links
notes / Notes All defined features except underline, content font family, content font size, and text color
full / Full All defined feature flags

Feature keys are bold, italic, underline, strike, code, links, headings, lists, tasks, tables, images, fontFamily, fontSize, textColor, quotes, codeBlocks, and thematicBreaks. C# uses the corresponding PascalCase EditorFeature enum.

Format compatibility is applied after preset selection. Plain-text storage disables rich features. Strict Markdown disables underline/font family/font size/text color. Explicitly enabling a feature incompatible with the format is an error; it is not silently converted to another format.

maxListDepth / MaxListDepth accepts 0 through 8. headingLevels / Options.HeadingLevels selects a subset of levels 1–6, including an empty subset. allowSourceView / AllowSourceView controls access to Source view. Switch to Visual before disabling Source on an existing instance.

Restricted comments example

const commentEditor = CODEEditor.create(element, {
  value: '', format: 'markdown', mode: 'rich', language: 'markdown',
  preset: 'basic', allowEmbeddedHtml: false, allowSourceView: false,
  unsupportedContent: 'reject'
});

editor.Preset = EditorPreset.Notes;
editor.AllowEmbeddedHtml = false;
editor.Options.SetFeature(EditorFeature.Images, false);
editor.Options.SetFeature(EditorFeature.Tables, false);
editor.Options.HeadingLevels = [2, 3];
editor.MaxListDepth = 3;

Set a policy before loading a document when possible. A policy change can invalidate existing content and resets undo/redo. JavaScript feature overrides merge with existing overrides; omitting a key does not remove an earlier override. C# Options.ResetFeatures() clears explicit overrides, while Options.Features reports the overrides, not the effective full policy. Query capabilities for the effective policy.

Unsupported-content handling

Handling Load/import behavior Save implication
preserve Retains unsupported content as opaque, noneditable raw content where supported Diagnostics remain; validated snapshot saving is blocked until resolved
reject Rejects the import/configuration that violates policy Host must handle the rejection and keep/recover the previous document
convert Flattens/removes unsupported features into a permitted representation May lose formatting or structure; inspect conversion/import reports

The default is Preserve. Preserve is not permission to bypass policy on save. getValue() can retrieve text that still has policy diagnostics; getSnapshot() checks them. A source user can type markup outside the permitted policy; the save validation is therefore important even if the toolbar hides forbidden commands.

The policy layer is for product consistency and validation. It is not a server authorization boundary, and callers who directly manipulate internal model objects can violate its assumptions.

Format conversion

Use convertFormat('html', { unsupportedContent: 'reject' }) or ConvertFormatAsync(EditorFormat.Html) for explicit Markdown/HTML conversion. It resets history and may change serialization. JavaScript returns { value, report, historyReset: true }; the .NET method returns Task, then updates accepted format/view/language through a snapshot.

Do not change Format merely to rename an existing string's type. For loading another document, use LoadAsync with a compatible view and language. For converting an existing document, use conversion explicitly. Text and RichJson are not destinations of the Markdown/HTML conversion method.

Source preservation and normalization

Unchanged source and supported block source metadata help avoid unnecessary rewrites. Visual edits may normalize emphasis delimiters, list syntax, table alignment separators, HTML fragments, and line endings in rebuilt regions. Source sessions retain their existing text, including mixed line endings, until an edit affects it. This is not a general lossless arbitrary-document guarantee; use a real document corpus as part of acceptance testing.

Previous
Next