https://github.com/eddyluten/mkdocs-live-edit-plugin
An MkDocs plugin that allows editing pages directly from the browser.
https://github.com/eddyluten/mkdocs-live-edit-plugin
documentation live-editing mkdocs mkdocs-plugin wiki
Last synced: 10 days ago
JSON representation
An MkDocs plugin that allows editing pages directly from the browser.
- Host: GitHub
- URL: https://github.com/eddyluten/mkdocs-live-edit-plugin
- Owner: EddyLuten
- License: mit
- Created: 2023-06-22T07:14:15.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-02-23T21:33:54.000Z (about 2 months ago)
- Last Synced: 2025-04-04T18:53:06.536Z (18 days ago)
- Topics: documentation, live-editing, mkdocs, mkdocs-plugin, wiki
- Language: Python
- Homepage:
- Size: 41 KB
- Stars: 25
- Watchers: 2
- Forks: 5
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# mkdocs-live-edit-plugin
[](https://pypi.org/project/mkdocs-live-edit-plugin/) [](https://opensource.org/licenses/MIT)  [](https://pepy.tech/project/mkdocs-live-edit-plugin)
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](https://github.com/EddyLuten/mkdocs-categories-plugin) and [mkdocs-alias-plugin](https://github.com/EddyLuten/mkdocs-alias-plugin).
## Installation
Using Python 3.10 or greater, install the package using pip:
```zsh
pip install mkdocs-live-edit-plugin
```
Then add the following entry to the plugins section of your `mkdocs.yml` file:
```yml
plugins:
- live-edit
```
## Usage
[](https://www.youtube.com/watch?v=8aUToGfXGVA)
```yml
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'
```
## How Does it Work?
The short answer: [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) 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](https://github.com/EddyLuten/mkdocs-categories-plugin)
- Integration with [mkdocs-alias-plugin](https://github.com/EddyLuten/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 syntaxt used by the [`querySelector`](https://developer.mozilla.org/en-US/docs/Web/API/Element/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.
## Changelog
### 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](https://github.com/EddyLuten/mkdocs-live-edit-plugin/issues/5). 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](https://github.com/EddyLuten/mkdocs-live-edit-plugin/issues/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](https://github.com/EddyLuten/mkdocs-live-edit-plugin/issues/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.