From c2e82ab744ad942220bbab1bcb038d7738b6671e Mon Sep 17 00:00:00 2001
From: John McLear <john@mclear.co.uk>
Date: Fri, 17 Apr 2026 12:27:26 +0100
Subject: [PATCH] docs: document the supported Etherpad plugin install flow
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Many operators reach for "npm i ep_<plugin>" because the README
doesn't say anything about how to install the plugin — but that
bypasses Etherpad's plugin-manager and tends to leave the server
unable to start (see e.g. ether/ep_table_of_contents#154). Add a
short, uniform Installation section that points at the admin UI or
"pnpm run plugins install" from the Etherpad root and explicitly
warns against hand-editing package.json.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/README.md b/README.md
index 9e4e592..b6a7cbc 100644
--- a/README.md
+++ b/README.md
@@ -40,3 +40,20 @@ Requirements
 ============
 
 Etherpad 1.8.1
+
+## Installation
+
+Install from the Etherpad admin UI (**Admin → Manage Plugins**,
+search for `ep_markdown` and click *Install*), or from the Etherpad
+root directory:
+
+```sh
+pnpm run plugins install ep_markdown
+```
+
+> ⚠️ Don't run `npm i` / `npm install` yourself from the Etherpad
+> source tree — Etherpad tracks installed plugins through its own
+> plugin-manager, and hand-editing `package.json` can leave the
+> server unable to start.
+
+After installing, restart Etherpad.