mkdocs-live-wysiwyg-plugin 0.2.5

WYSIWYG editor for mkdocs-live-edit-plugin based on @celsowm/markdown-wysiwyg

mkdocs-live-wysiwyg-plugin

A WYSIWYG (What-You-See-Is-What-You-Get) editor for mkdocs-live-edit-plugin, based on @celsowm/markdown-wysiwyg.

See shortcuts and behaviors document for how to edit documents.

• :rainbow::sparkles: Author quality of life features
  • :white_check_mark: Non-destructive WYSIWYG editing is a top priority. git diff will show changes the author intended. No extra mess typically associated with WYSIWYG editors.
  • :white_check_mark: Selected text to edit is the fastest flow. A small context menu pops up around selected text which enables the author to fix the issue right away.
  • :white_check_mark: Editor preferences remembered across pages. If the editor is disabled, then it will still be disabled when editing another document. WYGSIWYG or Markdown mode is also remembered when the Editor is enabled.
  • :white_check_mark: A URL pasted onto selected text creates a markdown link.
• :muscle: Mkdocs rendering features
  • :white_check_mark: Markdown checklists (task lists): - [ ] and - [x] render as clickable checkboxes in WYSIWYG. Toggle by clicking; new list items in a checklist create - [ ] automatically.
  • :white_check_mark: Dual-mode editing (WYSIWYG and Markdown) with toolbar formatting. The editor can also be disabled.
  • :white_check_mark: YAML frontmatter preserved when editing and switching modes.
  • :white_check_mark: MkDocs admonitions (!!! note, !!! warning, etc.). A UI button for inserting new admonitions.
  • :white_check_mark: Markdown link styles preserved (inline, reference, shortcut)
  • :white_check_mark: Code blocks with WYSIWYG editable titles.
  • :white_check_mark: Checklists with WYSIWYG editable state. A UI button for toggling an unordered list and checklist.
• :information_source: Other noteworthy features
  • :white_check_mark: Cursor location memory: when switching between WYSIWYG or Markdown modes the cursor location and scroll area is preserved to reduce editing strain on the author.
  • :white_check_mark: Selected text is preserved when the author switches modes (to/from wysiwyg or markdown).
  • :white_check_mark: Typing in with backticks inline will automatically convert text to inline code blocks.
  • :white_check_mark: No external JavaScript; all assets are bundled locally within the mkdocs plugin.

When you click "Edit" in the live-edit plugin, this plugin replaces the plain textarea with a rich WYSIWYG editor.

Requirements

• Python 3.10 or higher.
• mkdocs-live-edit-plugin (must be installed and configured)
• mkdocs >= 1.5

Installation

pip install mkdocs-live-wysiwyg-plugin

Or with uv:

uv pip install mkdocs-live-wysiwyg-plugin

This will install mkdocs-live-edit-plugin as a dependency. For development setup, see CONTRIBUTING.md.

Configuration

Add both plugins to your mkdocs.yml. Important: live-edit must be listed before live-wysiwyg:

plugins:
  - live-edit
  - live-wysiwyg:
      autoload_wysiwyg: true # optional, if false, start with plain textarea and show "Enable Editor"

Options

Option	Type	Default	Description
autoload_wysiwyg	boolean	true	Default behavior when no user preference cookie exists. If true, the WYSIWYG editor loads automatically when entering edit mode. If false, the plain textarea is shown initially with an "Enable Editor" button. Once the user explicitly enables or disables the editor, their preference is stored in a cookie and takes priority over this setting.

Attributions

This plugin incorporates or depends on the following works:

Component	Author	License	Link
@celsowm/markdown-wysiwyg (WYSIWYG editor)	Celso Fontes	MIT	GitHub · npm
marked (Markdown parser)	Christopher Jeffrey, MarkedJS	MIT	GitHub · marked.js.org
mkdocs-live-edit-plugin (required dependency)	Eddy Luten	MIT	GitHub

All listed components are distributed under the MIT License. See each project's repository for full license text.

The WYSIWYG editor and its dependencies (marked, editor.css, editor.js) are bundled locally in mkdocs_live_wysiwyg_plugin/vendor/—no external JavaScript or CSS is loaded at runtime.

MkDocs Theme Support

Only the Material for MkDocs theme is officially supported. Admonition styling and icons rely on Material theme CSS. Other themes may work but have not been tested.

Contributions to add support for other themes are welcome; see CONTRIBUTING.md. Material theme support is a requirement.

No breaking changes to Material theme compatibility are allowed.

MkDocs Admonitions

The WYSIWYG editor supports MkDocs admonition syntax (!!! note, !!! warning, etc.) in both modes:

• Markdown mode: Type !!! note followed by indented content (4 spaces)
• WYSIWYG mode: Admonitions render as styled callout boxes; editing preserves the !!! syntax when saving

Supported types: note, warning, danger, tip, hint, important, caution, error, attention.