mkdocs-live-edit-plugin

Important

This repository has moved to Codeberg.

The GitHub mirror is synced automatically, but please file issues and pull requests on Codeberg. See the CONTRIBUTING file for details. All existing issues and pull requests have also migrated there.

mkdocs-live-edit-plugin is an MkDocs plugin that allows editing pages directly from the browser.

Things you can do with this plugin when running via mkdocs serve:

• Editing a page's Markdown source from the page itself.
• Renaming a page's filename
• Deleting a page
• Creating a brand new page

Some basic editor shortcuts available while editing:

• Ctrl+B/Cmd+B toggles your selection to be Bold
• Ctrl+I/Cmd+I toggles your selection to be Italic
• Alt+S/Opt+S toggles your selection to be Strikethrough
• Ctrl+S/Cmd+S to save your changes

If you like this plugin, you'll probably also like mkdocs-categories-plugin and mkdocs-alias-plugin.

Installation

Using Python 3.10 or greater, install the package using pip:

pip install mkdocs-live-edit-plugin

Then add the following entry to the plugins section of your mkdocs.yml file:

plugins:
  - live-edit

Usage

plugins:
  - live-edit:
      # If, for any reason, you want to override the websocket host and/or port
      # that the Live Edit WebSocket is operating on, you can do so by changing
      # the following options:
      websockets_host: hostname # or any IP or hostname you wish
      websockets_port: 9999 # or any other port you want
      # By default, the plugin doesn't log any information to the browser
      # developer console other than errors. To make the output more verbose,
      # set the debug flag:
      debug_mode: true
      # If the plugin complains that the article element could not be found,
      # this option allow you to specify which selector to use to find it.
      # This string is directly fed into the document.querySelector function:
      # https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelector
      article_selector: 'div.my-custom-class'
      # Some plugins (e.g. mkdocs-monorepo-plugin) create a temporary docs_dir
      # which breaks live-edit. Use user_docs_dir to specify the real docs path:
      user_docs_dir: /path/to/real/user/docs

How Does it Work?

The short answer: WebSockets handle client-server communication, while MkDocs handles reloading when files change.

The Longer Answer

Once installed, when running your local live-reload server, the plugin registers a separate WebSockets server that runs on a specified port. Once your wiki is built, a WebSockets client is installed in your browser, allowing for asynchronous communication between the two.

When you edit the contents of a file in the browser, they are sent to the server via WebSockets, where the plugin writes the contents to disk. Here, MkDocs picks up on the change and sends a reload signal back to the browser -- this is the same live-reload mechanism that picks up on changes you make via a text editor.

A similar mechanism is in place for other operations like renaming and deleting.

TODO

• Moving pages (also not sure about handling directories here)
• Integration with mkdocs-categories-plugin
• Integration with mkdocs-alias-plugin

Troubleshooting

I can't use the plugin from a remote machine

Make sure that MkDocs binds to 0.0.0.0 (the default for MkDocs is 127.0.0.1) by specifying the following flag at startup: mkdocs serve -a 0.0.0.0:8000. The plugin will inherit this hostname (unless websockets_host is set in the plugin options).

"Could not find article element to prepend controls!"

The plugin was unable to automatically determine the element which houses the text of your article. You can use the article_selector setting to provide the correct selector syntax used by the querySelector function to find your article. This should be the parent element of your article's H1 tag, containing all of your article's text.

Live-edit doesn't work with mkdocs-monorepo-plugin (or similar plugins)

Some plugins create a temporary docs_dir which breaks live-edit. Use the user_docs_dir option to specify the real path to your documentation source files:

plugins:
  - live-edit:
      user_docs_dir: /path/to/real/user/docs

Changelog

0.4.1 (Mar 04, 2026)

Bug Fixes:

• Bug Fix: fix for a potential race condition when initializing the websocket connection.
• Bug Fix: fix for the CSS class live-edit-editing remaining when exiting edit mode.
• Minor feature: support for button access keys.

Thank you, @tim-janik, for these changes!

0.4.0 (Mar 03, 2026)

Features and Bug Fixes:

• Feature: support for custom documentation file directories through the new option user_docs_dir
• Bug fix: fix for a TypeError in the plugin config

Thank you, @samrocketman, for both of these changes!

0.3.1 (Feb 23, 2025)

Bug Fixes:

• Fixes an issue on Windows where the file's path name would populate using underscores rather than slashes. Fixes #11. Thank you, @ZeeWanderer for the contributing the fix!
• Allows for the setting of an article_selector option to specify which element on the page contains the page's text. This should greatly improve compatibility with just about any theme.

0.3.0 (Feb 21, 2025)

Features and Bug Fixes:

• Feature: websocket_host option for specifiying a hostname other than the one MkDocs uses. If not provided, the plugin uses the same host as your MkDocs config (127.0.0.1 by default).
• Feature: Made the plugin spam the browser console less. This can still be re-enabled by setting debug_mode to true in the live-edit section of your config file.
• Bug Fix: unpinned the websocket dependency and upgraded to the current version.
• Bug Fix: fixed incorrect path variable on Chrome on Windows.

0.2.1 (Dec 15, 2024)

Bug fix: fixes a compatibility issue reported in #5. This version also pins the websocket dependency to version 13 for the time being since upgrading would be an undertaking outside the scope of a small patch.

0.2.0 (Mar 6, 2024)

New Feature: Creating pages. The plugin now exposes a button that allows you to create a brand new page from any other page.

0.1.5 (Feb 7, 2024)

Bug fix: fixes an issue where the WebSocket connection would host on localhost over IPv6. See #3 for context.

0.1.4 (Jan 31, 2024)

Bug fix: Improved WebSocket connectivity and error handling. Updated the documentation to match.

0.1.3 (Jan 29, 2024)

Bug fix: The WebSocket connection now honors the hostname as supplied by the browser in window.location.hostname.

0.1.2 (Jun 23, 2023)

Bug fix: include missing data files

0.1.1 (Jun 23, 2023)

Bug fix: include non-python files in the package

0.1.0 (Jun 23, 2023)

Initial release with editing, renaming, and deletion logic in place.