From c2a6944a2f6dae4594e5373d7d984d07e89cd546 Mon Sep 17 00:00:00 2001
From: umbobabo <umberto.babini@ft.com>
Date: Tue, 14 Oct 2025 14:35:54 +0100
Subject: [PATCH] doc: JSDO doc approach

---
 README.md | 25 +++++++++++++++++--------
 1 file changed, 17 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 854b561..f0dba0d 100644
--- a/README.md
+++ b/README.md
@@ -766,20 +766,31 @@ interface CustomCodeComponent extends Node {
 ### Timeline
 
 ```ts
+/**
+ * Allowed layout widths for a Timeline.
+ * @typedef {'full-width' | 'inset-left' | 'full-grid'} TimelineLayoutWidth
+ */
 type TimelineLayoutWidth =  Extract<LayoutWidth, "full-width" | "inset-left" | "full-grid">
 
+/**
+ * Timeline nodes display a timeline of events in arbitrary order.
+ *
+ * @typedef Timeline
+ * @property {TimelineLayoutWidth} layoutWidth - How the component should be presented.
+ **/
 interface Timeline extends Parent {
 	type: "timeline"
 	layoutWidth: TimelineLayoutWidth
 	children: [Heading, ...TimelineEvent[]]
 }
-```
-
-**Timeline** nodes display a timeline of events in arbitrary order.
-
-### TimelineEvent
 
-```ts
+/**
+ * TimelineEvent is the representation of a single event
+ * 
+ * @typedef TimelineEvent
+ * @property {string} title - The title of the event
+ * @property {(Paragraph | ImageSet)[]} children - Elements that describe the event
+ **/
 interface TimelineEvent extends Parent {
 	type: "timeline-event"
 	title: string
@@ -787,8 +798,6 @@ interface TimelineEvent extends Parent {
 }
 ```
 
-**TimelineEvent** nodes represents a single event in a timeline.
-
 ## License
 
 This software is published by the Financial Times under the [MIT licence](mit).