mkdocs-live-wysiwyg-plugin

An all-in-one editor for GitHub and mkdocs documentation. Available from an extension store above or from GitHub release. Alternately available as a simple shell script.

1. Add techdocs-preview.sh to your $PATH.
2. Edit documentation across your projects.

techdocs-preview.sh init

techdocs-preview.sh -c -a docs

Features

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

• 🌈✨ Author quality of life features
  • 👁-👁 Focus mode with collapsible nav sidebar, editing tools, and table of contents.
  • 📝 Non-destructive editing is a top priority. Minimal git diff .
  • 🧜 Mermaid diagram editor with a unique feature: text on diagrams can be clicked to auto-select matching mermaid text. Enables fast editing of existing diagrams.
  • 🗂️ File management: reorder files, content migrations, dead link scanning (for broken internal or external links), preview and manage images. Refactors links to documents and intra-document links when headings are renamed.
  • 🔗 A URL pasted onto selected text creates a markdown link. Headings can be copied to create intra-document links. Hold Ctrl key to open links with a click.
  • 🍹🤌 Unified editor actions for WYSIWYG and Markdown modes (i.e. switching modes).
    • 🗡 Loss-less undo/redo history with a UI to access full redo history. Switching modes has shared undo history.
    • 🐁 Cursor location memory: switching modes keeps cursor and scroll area in same document location.
    • 🛰 Text selections are preserved when the author switches modes.
• 💪 Mkdocs/backage 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.
  • ✅ Automated content migration to mkdocs-nav-weight.
• ℹ️ Other noteworthy features
  • ✅ Auto-conversions: inline typing of markdown syntax creates formatted text.
  • ✅ Balanced ASCII table formatting with configurable max width and per-table overrides.
  • ✅ Context-sensitive help panel (Ctrl+?). Not as good as clippy 📎.
  • ✅ No external JavaScript; all assets are bundled locally within the mkdocs plugin.

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

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.

No breaking changes to Material theme compatibility are allowed.

Support for admonition syntax (e.g. !!! note, !!! warning, etc.). Admonitions render as they would when the site is built by mkdocs. Collapsible admonitions (??? type) and HTML details tags (!!! details) are also supported.

Attributions

This plugin incorporates or depends on the following works:

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.