1# Notion Rich Text Reference
2 
3This document provides comprehensive documentation for rich text objects in the Notion API.
4 
5## Rich Text Array Structure
6 
7Rich text in Notion is represented as an array of rich text objects. Each block or property that supports formatted text uses this structure:
8 
9```json
10{
11  "rich_text": [
12    {
13      "type": "text",
14      "text": {"content": "Hello "},
15      "annotations": {"bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default"},
16      "plain_text": "Hello ",
17      "href": null
18    },
19    {
20      "type": "text",
21      "text": {"content": "world", "link": {"url": "https://example.com"}},
22      "annotations": {"bold": true, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default"},
23      "plain_text": "world",
24      "href": "https://example.com"
25    }
26  ]
27}
28```
29 
30## Common Fields
31 
32All rich text objects contain:
33 
34| Field | Type | Description |
35|-------|------|-------------|
36| `type` | string | The type of rich text object |
37| `annotations` | object | Styling applied to the text |
38| `plain_text` | string | Plain text without formatting |
39| `href` | string or null | URL if the text is a link |
40 
41---
42 
43## Rich Text Types
44 
45### Text
46 
47Basic text content with optional link:
48 
49```json
50{
51  "type": "text",
52  "text": {
53    "content": "Link text",
54    "link": {"url": "https://example.com"}
55  },
56  "annotations": { /* ... */ },
57  "plain_text": "Link text",
58  "href": "https://example.com"
59}
60```
61 
62Without link:
63 
64```json
65{
66  "type": "text",
67  "text": {
68    "content": "Plain text"
69  },
70  "annotations": { /* ... */ },
71  "plain_text": "Plain text",
72  "href": null
73}
74```
75 
76### Equation
77 
78Inline mathematical expressions using LaTeX/KaTeX:
79 
80```json
81{
82  "type": "equation",
83  "equation": {
84    "expression": "E = mc^2"
85  },
86  "annotations": { /* ... */ },
87  "plain_text": "E = mc^2",
88  "href": null
89}
90```
91 
92### Mention
93 
94References to other Notion objects or users.
95 
96#### User Mention
97 
98```json
99{
100  "type": "mention",
101  "mention": {
102    "type": "user",
103    "user": {
104      "object": "user",
105      "id": "user-uuid",
106      "name": "John Doe",
107      "avatar_url": "https://...",
108      "type": "person",
109      "person": {"email": "[email protected]"}
110    }
111  },
112  "annotations": { /* ... */ },
113  "plain_text": "@John Doe",
114  "href": "https://www.notion.so/user-uuid"
115}
116```
117 
118#### Page Mention
119 
120```json
121{
122  "type": "mention",
123  "mention": {
124    "type": "page",
125    "page": {
126      "id": "page-uuid"
127    }
128  },
129  "annotations": { /* ... */ },
130  "plain_text": "Page Title",
131  "href": "https://www.notion.so/page-uuid"
132}
133```
134 
135**Note**: If the integration doesn't have access to the mentioned page, only the ID is returned.
136 
137#### Database Mention
138 
139```json
140{
141  "type": "mention",
142  "mention": {
143    "type": "database",
144    "database": {
145      "id": "database-uuid"
146    }
147  },
148  "annotations": { /* ... */ },
149  "plain_text": "Database Title",
150  "href": "https://www.notion.so/database-uuid"
151}
152```
153 
154#### Date Mention
155 
156```json
157{
158  "type": "mention",
159  "mention": {
160    "type": "date",
161    "date": {
162      "start": "2024-01-15",
163      "end": null,
164      "time_zone": null
165    }
166  },
167  "annotations": { /* ... */ },
168  "plain_text": "January 15, 2024",
169  "href": null
170}
171```
172 
173With date range:
174 
175```json
176{
177  "type": "mention",
178  "mention": {
179    "type": "date",
180    "date": {
181      "start": "2024-01-15",
182      "end": "2024-01-20",
183      "time_zone": null
184    }
185  },
186  "annotations": { /* ... */ },
187  "plain_text": "January 15, 2024 → January 20, 2024",
188  "href": null
189}
190```
191 
192#### Link Preview Mention
193 
194```json
195{
196  "type": "mention",
197  "mention": {
198    "type": "link_preview",
199    "link_preview": {
200      "url": "https://github.com/..."
201    }
202  },
203  "annotations": { /* ... */ },
204  "plain_text": "https://github.com/...",
205  "href": "https://github.com/..."
206}
207```
208 
209#### Template Mention (Date)
210 
211Used in template blocks for dynamic dates:
212 
213```json
214{
215  "type": "mention",
216  "mention": {
217    "type": "template_mention",
218    "template_mention": {
219      "type": "template_mention_date",
220      "template_mention_date": "today"
221    }
222  },
223  "annotations": { /* ... */ },
224  "plain_text": "@today",
225  "href": null
226}
227```
228 
229Template date options: `today`, `now`
230 
231#### Template Mention (User)
232 
233Used in template blocks for dynamic user references:
234 
235```json
236{
237  "type": "mention",
238  "mention": {
239    "type": "template_mention",
240    "template_mention": {
241      "type": "template_mention_user",
242      "template_mention_user": "me"
243    }
244  },
245  "annotations": { /* ... */ },
246  "plain_text": "@me",
247  "href": null
248}
249```
250 
251---
252 
253## Annotations
254 
255Annotations control text styling:
256 
257```json
258{
259  "annotations": {
260    "bold": false,
261    "italic": false,
262    "strikethrough": false,
263    "underline": false,
264    "code": false,
265    "color": "default"
266  }
267}
268```
269 
270| Property | Type | Description |
271|----------|------|-------------|
272| `bold` | boolean | Bold text |
273| `italic` | boolean | Italic text |
274| `strikethrough` | boolean | Strikethrough text |
275| `underline` | boolean | Underlined text |
276| `code` | boolean | Inline code styling |
277| `color` | string | Text or background color |
278 
279### Color Options
280 
281Text colors:
282- `default`
283- `gray`
284- `brown`
285- `orange`
286- `yellow`
287- `green`
288- `blue`
289- `purple`
290- `pink`
291- `red`
292 
293Background colors:
294- `gray_background`
295- `brown_background`
296- `orange_background`
297- `yellow_background`
298- `green_background`
299- `blue_background`
300- `purple_background`
301- `pink_background`
302- `red_background`
303 
304---
305 
306## Creating Rich Text
307 
308### Simple Text
309 
310```json
311[
312  {
313    "type": "text",
314    "text": {"content": "Simple text"}
315  }
316]
317```
318 
319### Formatted Text
320 
321```json
322[
323  {
324    "type": "text",
325    "text": {"content": "Bold and italic"},
326    "annotations": {"bold": true, "italic": true}
327  }
328]
329```
330 
331### Mixed Formatting
332 
333```json
334[
335  {"type": "text", "text": {"content": "Normal "}},
336  {"type": "text", "text": {"content": "bold"}, "annotations": {"bold": true}},
337  {"type": "text", "text": {"content": " and "}},
338  {"type": "text", "text": {"content": "italic"}, "annotations": {"italic": true}},
339  {"type": "text", "text": {"content": " text."}}
340]
341```
342 
343### Text with Link
344 
345```json
346[
347  {"type": "text", "text": {"content": "Check out "}},
348  {
349    "type": "text",
350    "text": {"content": "this link", "link": {"url": "https://example.com"}}
351  },
352  {"type": "text", "text": {"content": " for more info."}}
353]
354```
355 
356### Code Styling
357 
358```json
359[
360  {"type": "text", "text": {"content": "Use the "}},
361  {"type": "text", "text": {"content": "console.log()"}, "annotations": {"code": true}},
362  {"type": "text", "text": {"content": " function."}}
363]
364```
365 
366### Colored Text
367 
368```json
369[
370  {
371    "type": "text",
372    "text": {"content": "Important!"},
373    "annotations": {"color": "red", "bold": true}
374  }
375]
376```
377 
378### With Background Color
379 
380```json
381[
382  {
383    "type": "text",
384    "text": {"content": "Highlighted text"},
385    "annotations": {"color": "yellow_background"}
386  }
387]
388```
389 
390### User Mention
391 
392```json
393[
394  {"type": "text", "text": {"content": "Assigned to "}},
395  {
396    "type": "mention",
397    "mention": {
398      "type": "user",
399      "user": {"id": "user-uuid"}
400    }
401  }
402]
403```
404 
405### Page Mention
406 
407```json
408[
409  {"type": "text", "text": {"content": "See also: "}},
410  {
411    "type": "mention",
412    "mention": {
413      "type": "page",
414      "page": {"id": "page-uuid"}
415    }
416  }
417]
418```
419 
420### Date Mention
421 
422```json
423[
424  {"type": "text", "text": {"content": "Due: "}},
425  {
426    "type": "mention",
427    "mention": {
428      "type": "date",
429      "date": {"start": "2024-12-31"}
430    }
431  }
432]
433```
434 
435### Inline Equation
436 
437```json
438[
439  {"type": "text", "text": {"content": "The formula is "}},
440  {"type": "equation", "equation": {"expression": "x = \\frac{-b \\pm \\sqrt{b^2-4ac}}{2a}"}},
441  {"type": "text", "text": {"content": "."}}
442]
443```
444 
445---
446 
447## Limits
448 
449| Type | Limit |
450|------|-------|
451| Rich text content | 2000 characters per rich text object |
452| Rich text array | 100 items max |
453| Equations | 1000 characters |
454 
455---
456 
457## Reading Rich Text
458 
459When processing rich text from API responses, you can:
460 
4611. **Get plain text**: Concatenate all `plain_text` values
4622. **Preserve formatting**: Process each object and apply `annotations`
4633. **Extract links**: Check `href` field or `text.link.url`
464 
465Example (JavaScript):
466 
467```javascript
468function getPlainText(richTextArray) {
469  return richTextArray.map(rt => rt.plain_text).join('');
470}
471 
472function getLinks(richTextArray) {
473  return richTextArray
474    .filter(rt => rt.href)
475    .map(rt => ({text: rt.plain_text, url: rt.href}));
476}
477```
478 
479Example (bash with jq):
480 
481```bash
482# Get plain text
483echo "$rich_text_json" | jq -r '[.[].plain_text] | join("")'
484 
485# Get all links
486echo "$rich_text_json" | jq '[.[] | select(.href != null) | {text: .plain_text, url: .href}]'
487```
488