eddyluten / mkdocs-live-edit-plugin

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

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 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

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:

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

TODO

• Creating new pages (not sure how picking directories would work)
• Moving pages (also not sure about handling directories here)
• Integration with mkdocs-categories-plugin
• Integration with mkdocs-alias-plugin

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.

Changelog

0.2.0

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

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

0.1.4

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

0.1.3

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

0.1.2

Bug fix: include missing data files

0.1.1

Bug fix: include non-python files in the package

0.1.0

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

mkdocs-live-edit-plugin's Issues

OSError: [Errno 99] error while attempting to bind on address ('::1', 8484, 0, 0): cannot assign requested address

Python version(s): 3.10.13 / 3.11.7

mkdocs-live-edit-plugin = "^0.1.4"

...
INFO    -  Documentation built in 21.14 seconds
INFO    -  live-edit websocket server starting
INFO    -  live-edit websocket server thread started
Exception in thread Thread-5 (server_thread_main):
Traceback (most recent call last):
  File "/home/user/.pyenv/versions/3.10.13/lib/python3.10/threading.py", line 1016, in _bootstrap_inner
    self.run()
  File "/home/user/.pyenv/versions/3.10.13/lib/python3.10/threading.py", line 953, in run
    self._target(*self._args, **self._kwargs)
  File ".venv/lib/python3.10/site-packages/live/plugin.py", line 221, in server_thread_main
    asyncio.run(self.event_loop())
  File "/home/user/.pyenv/versions/3.10.13/lib/python3.10/asyncio/runners.py", line 44, in run
    return loop.run_until_complete(main)
  File "/home/user/.pyenv/versions/3.10.13/lib/python3.10/asyncio/base_events.py", line 649, in run_until_complete
    return future.result()
  File ".venv/lib/python3.10/site-packages/live/plugin.py", line 207, in event_loop
    async with serve(
  File ".venv/lib/python3.10/site-packages/websockets/legacy/server.py", line 1098, in __aenter__
    return await self
  File ".venv/lib/python3.10/site-packages/websockets/legacy/server.py", line 1116, in __await_impl__
    server = await self._create_server()
  File "/home/user/.pyenv/versions/3.10.13/lib/python3.10/asyncio/base_events.py", line 1519, in create_server
    raise OSError(err.errno, 'error while attempting '
OSError: [Errno 99] error while attempting to bind on address ('::1', 8484, 0, 0): cannot assign requested address
INFO    -  [09:28:22] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [09:28:22] Serving on http://127.0.0.1:8000/

Fix:

/live/plugin.py

async with serve(
        self.websocket_receiver,
        "localhost",
        self.config['websockets_port']
    ):
    ...

async with serve(
        self.websocket_receiver,
        "127.0.0.1",
        self.config['websockets_port']
    ):
    ...

PR coming shortly 😃

Edit failing while attempted to edit from other devices

• As show on the image , the web socket is running on the local-host , from same device edit is functioning correctly but from the other devices it is giving the above provided issue .
• Can you please have a look at it and also if there is anything i am missing then let me know

Can't establish a connection to the websocket server

I have the similar problem. The Edit button not responding.

Originally posted by @noeldum in #1 (comment)