diff --git a/diagrams/class-diagrams/README.md b/diagrams/class-diagrams/README.md
new file mode 100644
index 000000000..f1d33317c
--- /dev/null
+++ b/diagrams/class-diagrams/README.md
@@ -0,0 +1,37 @@
+# Class Diagrams for GOV.UK Forms apps
+
+The mermaid files in this directory are [Class Diagrams](https://mermaid.js.org/syntax/classDiagram.html) for each of the apps we run that make up the main GOV.UK Forms system.
+
+## How to generate
+
+In each app, install the `rails-erd` gem:
+
+```ruby
+group :development do
+  gem "rails-erd", git: "https://github.com/voormedia/rails-erd.git"
+end
+```
+
+We need the latest version in the repo, as at the time of writing the most recent release does not include [Mermaid support](https://github.com/voormedia/rails-erd/commit/22cfc76098e222b7c211f0369e80580aeaa22c70).
+
+> ⚠️ Note: Do not commit the gem into the app repos.
+
+Run:
+
+```shell
+generator="mermaid" rake erd
+```
+
+This will create a file called `erd.mmd` in the root of the application.
+
+## Update the diagram
+
+1. Open the file in an editor and copy the contents (all of the `classDiagram` block).
+2. Paste the contents into the corresponding diagram file, replacing everything inside the "mermaid" block:
+````
+```mermaid
+classDiagram
+...
+```
+````
+3. Update the date near the top of the file.
diff --git a/diagrams/admin-erd.mmd b/diagrams/class-diagrams/admin.md
similarity index 94%
rename from diagrams/admin-erd.mmd
rename to diagrams/class-diagrams/admin.md
index 17766f15c..c1eb4680b 100644
--- a/diagrams/admin-erd.mmd
+++ b/diagrams/class-diagrams/admin.md
@@ -1,3 +1,11 @@
+---
+title: GOV.UK Forms Admin app class diagram
+---
+
+# GOV.UK Forms Admin app class diagram
+## 2025-05-29
+
+```mermaid
 classDiagram
 	direction RL
 	class `CreateFormService::CreateFormEvent`
@@ -77,4 +85,5 @@ classDiagram
 	`Organisation` --> `Group`
 	`Organisation` --> `MouSignature`
 	`Group` --> `Membership`
-	`Group` --> `GroupForm`
\ No newline at end of file
+	`Group` --> `GroupForm`
+  ```
diff --git a/diagrams/api-erd.mmd b/diagrams/class-diagrams/api.md
similarity index 95%
rename from diagrams/api-erd.mmd
rename to diagrams/class-diagrams/api.md
index 4576c53c4..5af79ddf7 100644
--- a/diagrams/api-erd.mmd
+++ b/diagrams/class-diagrams/api.md
@@ -1,3 +1,11 @@
+---
+title: GOV.UK Forms API class diagram
+---
+
+# GOV.UK Forms API class diagram
+## 2025-05-29
+
+```mermaid
 classDiagram
 	direction RL
 	class `AccessToken`
@@ -86,4 +94,5 @@ classDiagram
 	`Page` --> `Condition`
 	`Form` --> `MadeLiveForm`
 	`Form` --> `Api::V2::FormDocument`
-	`Condition` .. `Form`
\ No newline at end of file
+	`Condition` .. `Form`
+```
diff --git a/diagrams/runner-erd.mmd b/diagrams/class-diagrams/runner.md
similarity index 64%
rename from diagrams/runner-erd.mmd
rename to diagrams/class-diagrams/runner.md
index 4c74ae7f6..97d21e042 100644
--- a/diagrams/runner-erd.mmd
+++ b/diagrams/class-diagrams/runner.md
@@ -1,3 +1,11 @@
+---
+title: GOV.UK Forms Runner app class diagram
+---
+
+# GOV.UK Forms Runner app class diagram
+## 2025-05-29
+
+```mermaid
 classDiagram
 	direction RL
 	class `Submission`
@@ -8,4 +16,5 @@ classDiagram
 	`Submission` : +string mail_status
 	`Submission` : +string mode
 	`Submission` : +string reference
-	`Submission` : +datetime sent_at
\ No newline at end of file
+	`Submission` : +datetime sent_at
+  ```