From d9a4858b1da8b1efbbe5789c6ddb4de79cfa2565 Mon Sep 17 00:00:00 2001
From: Florian Duros <florianduros@element.io>
Date: Fri, 16 Jan 2026 17:06:24 +0100
Subject: [PATCH] doc: update module doc (#31775)

---
 README.md                                  | 11 +++++++++++
 docs/SUMMARY.md                            |  2 +-
 docs/{modules.md => depredated-modules.md} |  5 ++++-
 3 files changed, 16 insertions(+), 2 deletions(-)
 rename docs/{modules.md => depredated-modules.md} (94%)

diff --git a/README.md b/README.md
index 6f6e3172fa..bf0e10551d 100644
--- a/README.md
+++ b/README.md
@@ -194,6 +194,17 @@ To add a new translation, head to the [translating doc](docs/translating.md).
 
 For a developer guide, see the [translating dev doc](docs/translating-dev.md).
 
+# Extending Element Web with Modules
+
+Element Web supports a module system that allows you to extend or modify functionality at runtime. Modules are loaded dynamically and provide a safe, predictable API for customization.
+
+## What are modules?
+
+Modules are extensions that can add or modify Element Web's functionality. They are:
+
+- Built using the [`@element-hq/element-web-module-api`](https://github.com/element-hq/element-modules/tree/main/packages/element-web-module-api)
+- Loaded in EW via [config.json](docs/config.md#modules)
+
 # Triaging issues
 
 Issues are triaged by community members and the Web App Team, following the [triage process](https://github.com/element-hq/element-meta/wiki/Triage-process).
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 8e2b2d0150..711b7f47e0 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -19,7 +19,7 @@
 # Build
 
 - [Customisations](customisations.md)
-- [Modules](modules.md)
+- [Deprecated Modules](deprecated-modules.md)
 - [Native Node modules](native-node-modules.md)
 
 # Contribution
diff --git a/docs/modules.md b/docs/depredated-modules.md
similarity index 94%
rename from docs/modules.md
rename to docs/depredated-modules.md
index 68dabd29f8..b6a0b85711 100644
--- a/docs/modules.md
+++ b/docs/depredated-modules.md
@@ -1,4 +1,7 @@
-# Module system
+# Deprecated Module system
+
+> [!CAUTION]
+> DEPRECATED. Use [Element web module api](https://github.com/element-hq/element-modules/tree/main/packages/element-web-module-api) instead.
 
 The module system in Element Web is a way to add or modify functionality of Element Web itself, bundled at compile time
 for the app. This means that modules are loaded as part of the `yarn build` process but have an effect on user experience