{"id":15017521,"url":"https://github.com/eddyluten/mkdocs-live-edit-plugin","last_synced_at":"2026-03-04T06:07:49.590Z","repository":{"id":176438794,"uuid":"657036141","full_name":"EddyLuten/mkdocs-live-edit-plugin","owner":"EddyLuten","description":"An MkDocs plugin that allows editing pages directly from the browser.","archived":false,"fork":false,"pushed_at":"2025-02-23T21:33:54.000Z","size":42,"stargazers_count":25,"open_issues_count":4,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-04T18:53:06.536Z","etag":null,"topics":["documentation","live-editing","mkdocs","mkdocs-plugin","wiki"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EddyLuten.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-22T07:14:15.000Z","updated_at":"2025-03-29T16:25:16.000Z","dependencies_parsed_at":"2024-09-16T07:02:57.294Z","dependency_job_id":null,"html_url":"https://github.com/EddyLuten/mkdocs-live-edit-plugin","commit_stats":{"total_commits":18,"total_committers":2,"mean_commits":9.0,"dds":0.05555555555555558,"last_synced_commit":"59b9f883e3d197970b62bedf0f055d847e3b6325"},"previous_names":["eddyluten/mkdocs-live-edit-plugin"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyLuten%2Fmkdocs-live-edit-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyLuten%2Fmkdocs-live-edit-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyLuten%2Fmkdocs-live-edit-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyLuten%2Fmkdocs-live-edit-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EddyLuten","download_url":"https://codeload.github.com/EddyLuten/mkdocs-live-edit-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248564264,"owners_count":21125406,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","live-editing","mkdocs","mkdocs-plugin","wiki"],"created_at":"2024-09-24T19:50:36.313Z","updated_at":"2026-03-04T06:07:49.584Z","avatar_url":"https://github.com/EddyLuten.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mkdocs-live-edit-plugin\n\n[![PyPI version](https://badge.fury.io/py/mkdocs-live-edit-plugin.svg)](https://pypi.org/project/mkdocs-live-edit-plugin/)  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) ![example workflow](https://github.com/eddyluten/mkdocs-live-edit-plugin/actions/workflows/pylint.yml/badge.svg) [![Downloads](https://pepy.tech/badge/mkdocs-live-edit-plugin)](https://pepy.tech/project/mkdocs-live-edit-plugin)\n\nmkdocs-live-edit-plugin is an MkDocs plugin that allows editing pages directly from the browser.\n\nThings you can do with this plugin when running via `mkdocs serve`:\n\n- Editing a page's Markdown source from the page itself.\n- Renaming a page's filename\n- Deleting a page\n- Creating a brand new page\n\nSome basic editor shortcuts available while editing:\n\n- Ctrl+B/Cmd+B toggles your selection to be **Bold**\n- Ctrl+I/Cmd+I toggles your selection to be _Italic_\n- Alt+S/Opt+S toggles your selection to be ~~Strikethrough~~\n- Ctrl+S/Cmd+S to save your changes\n\nIf 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).\n\n## Installation\n\nUsing Python 3.10 or greater, install the package using pip:\n\n```zsh\npip install mkdocs-live-edit-plugin\n```\n\nThen add the following entry to the plugins section of your `mkdocs.yml` file:\n\n```yml\nplugins:\n  - live-edit\n```\n\n## Usage\n\n[![A video showing how to use v0.1.0](https://img.youtube.com/vi/8aUToGfXGVA/0.jpg)](https://www.youtube.com/watch?v=8aUToGfXGVA)\n\n```yml\nplugins:\n  - live-edit:\n      # If, for any reason, you want to override the websocket host and/or port\n      # that the Live Edit WebSocket is operating on, you can do so by changing\n      # the following options:\n      websockets_host: hostname # or any IP or hostname you wish\n      websockets_port: 9999 # or any other port you want\n      # By default, the plugin doesn't log any information to the browser\n      # developer console other than errors. To make the output more verbose,\n      # set the debug flag:\n      debug_mode: true\n      # If the plugin complains that the article element could not be found,\n      # this option allow you to specify which selector to use to find it.\n      # This string is directly fed into the document.querySelector function:\n      # https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelector\n      article_selector: 'div.my-custom-class'\n      # Some plugins (e.g. mkdocs-monorepo-plugin) create a temporary docs_dir\n      # which breaks live-edit. Use user_docs_dir to specify the real docs path:\n      user_docs_dir: /path/to/real/user/docs\n```\n\n## How Does it Work?\n\nThe 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.\n\n### The Longer Answer\n\nOnce 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.\n\nWhen 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.\n\nA similar mechanism is in place for other operations like renaming and deleting.\n\n## TODO\n\n- Moving pages (also not sure about handling directories here)\n- Integration with [mkdocs-categories-plugin](https://github.com/EddyLuten/mkdocs-categories-plugin)\n- Integration with [mkdocs-alias-plugin](https://github.com/EddyLuten/mkdocs-alias-plugin)\n\n### Troubleshooting\n\n#### ⚠️ I can't use the plugin from a remote machine\n\n✅ 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).\n\n#### ⚠️ \"Could not find article element to prepend controls!\"\n\nThe 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`](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.\n\n#### ⚠️ Live-edit doesn't work with mkdocs-monorepo-plugin (or similar plugins)\n\nSome 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:\n\n```yml\nplugins:\n  - live-edit:\n      user_docs_dir: /path/to/real/user/docs\n```\n\n## Changelog\n\n### 0.4.0 (Mar 03, 2026)\n\n**Features and Bug Fixes:**\n\n- Feature: support for custom documentation file directories through the new option `user_docs_dir`\n- Bug fix: fix for a TypeError in the plugin config\n\nThank you, @samrocketman, for both of these changes!\n\n### 0.3.1 (Feb 23, 2025)\n\n**Bug Fixes:**\n\n- 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!\n- 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.\n\n### 0.3.0 (Feb 21, 2025)\n\n**Features and Bug Fixes:**\n\n- 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).\n- 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.\n- Bug Fix: unpinned the websocket dependency and upgraded to the current version.\n- Bug Fix: fixed incorrect path variable on Chrome on Windows.\n\n### 0.2.1 (Dec 15, 2024)\n\n**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.\n\n### 0.2.0 (Mar 6, 2024)\n\n**New Feature:** Creating pages. The plugin now exposes a button that allows you to create a brand new page from any other page.\n\n### 0.1.5 (Feb 7, 2024)\n\n**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.\n\n### 0.1.4 (Jan 31, 2024)\n\n**Bug fix:** Improved WebSocket connectivity and error handling. Updated the documentation to match.\n\n### 0.1.3 (Jan 29, 2024)\n\n**Bug fix:** The WebSocket connection now honors the hostname as supplied by the browser in `window.location.hostname`.\n\n### 0.1.2 (Jun 23, 2023)\n\n**Bug fix:** include missing data files\n\n### 0.1.1 (Jun 23, 2023)\n\n**Bug fix:** include non-python files in the package\n\n### 0.1.0 (Jun 23, 2023)\n\nInitial release with editing, renaming, and deletion logic in place.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddyluten%2Fmkdocs-live-edit-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feddyluten%2Fmkdocs-live-edit-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddyluten%2Fmkdocs-live-edit-plugin/lists"}