mkdocs-live-wysiwyg-plugin 0.3.18

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

mkdocs-live-wysiwyg-plugin

This plugin is intended to be used by the techdocs-preview.sh shell script. It is assumed to be in your $PATH.

Try it out

Run ./techdocs-preview.sh from this repository to view the documentation for this repository.

For a general tutorial, you can run

techdocs-preview.sh init

The init command will initialize mkdocs documentation for you. The default docs serve as a tutorial to the WYSIWYG editor but you could also discard the documentation and use it as a starting point for your own project. init is intended to be a quick way to add documentation to a repository that did not previously have TechDocs.

I modify GitHub documentation for this repository with the following command.

techdocs-preview.sh -c -a docs

Features

A WYSIWYG (What-You-See-Is-What-You-Get) editor for exiting mkdocs documentation.

See shortcuts and behaviors document for how to edit documents.

• 🌈✨ Author quality of life features
  • 👁-👁 Focus mode with collapsible nav sidebar, editing tools, and table of contents.
  • ✅ Non-destructive WYSIWYG editing is a top priority. Minimal git diff .
  • ✅ Content refactoring with automated content migration.
    • Link refactoring when moving around documents.
    • Inner heading link refactoring when renaming headings within documents that are cross-referenced as links.
  • ✅ Editing preferences remembered across pages.
  • ✅ A URL pasted onto selected text creates a markdown link.
  • ✅ Automated content migration to mkdocs-nav-weight.
  • ✅ DAG-based undo/redo with branch picker for non-linear editing history. Undo works across markdown and WYSIWYG modes.
• 🗂️ Navigation management
  • ✅ Sidebar nav editing: reorder pages and sections with keyboard shortcuts or mouse.
  • ✅ Create, rename, and delete pages and folders from the nav sidebar.
  • ✅ Move pages between folders (indent/outdent).
  • ✅ Group selection with Ctrl/Cmd+Click for batch operations.
  • ✅ Nav-specific undo/redo stack (separate from content undo).
  • ✅ Review Changes popup before saving.
  • ✅ Automated dead link detection and resolution.
  • ✅ mkdocs-nav-weight integration with migration wizard.
• 💪 Mkdocs/backstage rendering features
  • ✅ Toggle-able checklists (task lists): - [ ] and - [x] .
  • ✅ YAML frontmatter preserved when editing and switching modes.
  • ✅ MkDocs admonitions (!!! note, !!! warning, etc.) with settings gear for type, collapsible, placement, and more.
  • ✅ Markdown link styles preserved (inline, reference, shortcut).
  • ✅ Code blocks with WYSIWYG editable titles, language selector, and auto-indent settings.
  • ✅ Mermaid diagram editing with an embedded live editor (full-screen overlay).
  • ✅ Tables with contextual toolbar: insert/delete rows and columns, column alignment, and formatting settings.
  • ✅ Image dialog with autocomplete from the docs tree.
  • ✅ Emoji shortcode completion and full emoji picker.
• ℹ️ Other noteworthy features
  • ✅ 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.
  • ✅ Selected text is preserved when the author switches modes (to/from wysiwyg or markdown).
  • ✅ Auto-conversions: typing markdown syntax (headings, lists, bold, inline code, etc.) in WYSIWYG mode converts live to formatted elements.
  • ✅ Balanced ASCII table formatting with configurable max width and per-table overrides.
  • ✅ Context-sensitive help panel (Ctrl+?).
  • ✅ No external JavaScript; all assets are bundled locally within the mkdocs plugin.

The following is an annotated screenshot after running techdocs-preview.sh init.

Requirements

The following requirements are automatically managed by techdocs-preview.sh with uv.

• Python 3.10 or higher.
• mkdocs-live-edit-plugin (must
• mkdocs >= 1.5

Installation

If not using techdocs-preview.sh:

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

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.
user_docs_dir	string	""	Override the docs source directory path. Useful when the monorepo plugin (e.g. techdocs-core) replaces docs_dir with a temporary directory. Falls back to the upstream mkdocs-live-edit-plugin's user_docs_dir, then to the MkDocs docs_dir.

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
js-yaml (YAML parser)	Vitaly Puzrin	MIT	GitHub
mermaid (Diagram renderer)	Knut Sveidqvist	MIT	GitHub · mermaid.js.org
mermaid-live-editor (Diagram editor)	Knut Sveidqvist	MIT	GitHub
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.

All vendored JavaScript, CSS, and application builds are bundled locally in mkdocs_live_wysiwyg_plugin/vendor/ — no external JavaScript or CSS is loaded at runtime. See vendor/README.md for exact versions and license files.

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 with a settings gear for type, collapsible toggle, placement, and more. Editing preserves the !!! syntax when saving.

Supported types: note, warning, danger, tip, hint, important, caution, error, attention, abstract, info, success, question, failure, bug, example, quote.

Collapsible admonitions (??? type) and HTML details tags (!!! details) are also supported.