An MkDocs plugin that allows editing pages directly from the browser.

mkdocs, python, markdown, editing, authoring, wiki, server, documentation, live-editing, mkdocs-plugin
pip install mkdocs-live-edit-plugin==0.2.0



PyPI version License: MIT example workflow Downloads

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.


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:

  - live-edit


A video showing how to use v0.1.0

If, for any reason, you want to override the port that the Live Edit WebSocket is operating on, you can do so by setting the websockets_port option for the live-edit plugin like so:

  - live-edit:
      websockets_port: 9999 # or any other port you want


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.



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


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


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


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


Bug fix: include missing data files


Bug fix: include non-python files in the package


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