Skip to content

Commit d0edf1b

Browse files
rephusrephus
authored
docs: extend rich text docs and images (#561)
* docs: extend rich text docs and images * trigger mintlify
1 parent 25704e5 commit d0edf1b

5 files changed

Lines changed: 122 additions & 15 deletions

File tree

‎images/references/rich-text-basic-markdown-links.png‎

110 KB
Loading

‎images/references/rich-text-conditional-tiers.png‎

93.9 KB
Loading

‎images/references/rich-text-hero.png‎

255 KB
Loading

‎images/references/rich-text-html-avatars.png‎

80.4 KB
Loading

‎references/dimensions.mdx‎

Lines changed: 122 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1089,13 +1089,17 @@ This URL will only work if I have `customer_id` included in my results table.
10891089

10901090
The `richText` property allows you to define custom HTML/Markdown templates for displaying dimension and metric values in table cells. This enables sophisticated data presentation with formatting, styling, conditional logic, and external integrations.
10911091

1092+
![Rich text examples rendered in a Table chart](/images/references/rich-text-hero.png)
1093+
10921094
<Info>
1093-
Rich text only affects UI display in table cells. It has no impact on value formatting, CSV exports, or the underlying data values.
1095+
Rich text only renders in the **Table chart visualization**. It does not affect the Results panel below the explore, CSV/Excel exports, or the underlying data values. To see your `richText` take effect, switch the chart type to **Table**.
10941096
</Info>
10951097

1098+
`richText` is supported on both **dimensions** and **metrics**. It accepts Markdown, inline HTML, and [LiquidJS](https://liquidjs.com/) templating. HTML is sanitized with a GitHub-safe allowlist that permits inline `style` attributes but strips `<script>`, `<iframe>`, and event handlers (e.g. `onclick`). External links automatically open in a new tab.
1099+
10961100
### Basic example
10971101

1098-
Display a dimension value with custom formatting:
1102+
Display a dimension value with bold text, an inline code span, and clickable links:
10991103

11001104
<Tabs>
11011105
<Tab title="dbt v1.9 and earlier">
@@ -1107,8 +1111,8 @@ Display a dimension value with custom formatting:
11071111
dimension:
11081112
richText: |
11091113
**Customer ID:** `${ value.raw }`
1110-
1111-
[View Profile](https://example.com/customer/${ value.raw })
1114+
1115+
[View Profile](https://example.com/customer/${ value.raw }) | [Search Google](https://google.com/search?q=customer%20${ value.formatted | url_encode })
11121116
```
11131117
</Tab>
11141118
<Tab title="dbt v1.10+ and Fusion">
@@ -1121,8 +1125,8 @@ Display a dimension value with custom formatting:
11211125
dimension:
11221126
richText: |
11231127
**Customer ID:** `${ value.raw }`
1124-
1125-
[View Profile](https://example.com/customer/${ value.raw })
1128+
1129+
[View Profile](https://example.com/customer/${ value.raw }) | [Search Google](https://google.com/search?q=customer%20${ value.formatted | url_encode })
11261130
```
11271131
</Tab>
11281132
<Tab title="Lightdash YAML">
@@ -1132,15 +1136,17 @@ Display a dimension value with custom formatting:
11321136
description: 'Unique customer identifier'
11331137
richText: |
11341138
**Customer ID:** `${ value.raw }`
1135-
1136-
[View Profile](https://example.com/customer/${ value.raw })
1139+
1140+
[View Profile](https://example.com/customer/${ value.raw }) | [Search Google](https://google.com/search?q=customer%20${ value.formatted | url_encode })
11371141
```
11381142
</Tab>
11391143
</Tabs>
11401144
1145+
![Cells rendered with a bold "Customer ID:" label, a code-style ID, and two inline links per row](/images/references/rich-text-basic-markdown-links.png)
1146+
11411147
### Conditional formatting
11421148
1143-
Use Liquid control flow tags for conditional display based on values:
1149+
Use Liquid control flow tags to switch rendering based on the value — for example, to tier a metric with emoji indicators and a matching text label. Always guard against `nil` so empty cells render gracefully:
11441150

11451151
<Tabs>
11461152
<Tab title="dbt v1.9 and earlier">
@@ -1152,15 +1158,17 @@ Use Liquid control flow tags for conditional display based on values:
11521158
average_clv:
11531159
type: average
11541160
richText: |
1155-
{% raw %}{% if value.raw >= 100 %}
1161+
{% raw %}{% if value.raw == nil %}
1162+
<span style="color: #999;">No data</span>
1163+
{% elsif value.raw >= 100 %}
11561164
### 📈 ${ value.formatted }
11571165
**Excellent** Average CLV
11581166
{% elsif value.raw >= 50 %}
11591167
### 📊 ${ value.formatted }
11601168
**Good** Average CLV
11611169
{% else %}
11621170
### ⚠️ ${ value.formatted }
1163-
**Low** Average CLV
1171+
**Low** Average CLV - _Needs attention!_
11641172
{% endif %}{% endraw %}
11651173
```
11661174
</Tab>
@@ -1174,15 +1182,17 @@ Use Liquid control flow tags for conditional display based on values:
11741182
average_clv:
11751183
type: average
11761184
richText: |
1177-
{% raw %}{% if value.raw >= 100 %}
1185+
{% raw %}{% if value.raw == nil %}
1186+
<span style="color: #999;">No data</span>
1187+
{% elsif value.raw >= 100 %}
11781188
### 📈 ${ value.formatted }
11791189
**Excellent** Average CLV
11801190
{% elsif value.raw >= 50 %}
11811191
### 📊 ${ value.formatted }
11821192
**Good** Average CLV
11831193
{% else %}
11841194
### ⚠️ ${ value.formatted }
1185-
**Low** Average CLV
1195+
**Low** Average CLV - _Needs attention!_
11861196
{% endif %}{% endraw %}
11871197
```
11881198
</Tab>
@@ -1193,20 +1203,117 @@ Use Liquid control flow tags for conditional display based on values:
11931203
type: average
11941204
sql: ${customer_lifetime_value}
11951205
richText: |
1196-
{% raw %}{% if value.raw >= 100 %}
1206+
{% raw %}{% if value.raw == nil %}
1207+
<span style="color: #999;">No data</span>
1208+
{% elsif value.raw >= 100 %}
11971209
### 📈 ${ value.formatted }
11981210
**Excellent** Average CLV
11991211
{% elsif value.raw >= 50 %}
12001212
### 📊 ${ value.formatted }
12011213
**Good** Average CLV
12021214
{% else %}
12031215
### ⚠️ ${ value.formatted }
1204-
**Low** Average CLV
1216+
**Low** Average CLV - _Needs attention!_
1217+
{% endif %}{% endraw %}
1218+
```
1219+
</Tab>
1220+
</Tabs>
1221+
1222+
![Conditional tiers rendered with emoji, bold and italic text, and a grey "No data" fallback for null values](/images/references/rich-text-conditional-tiers.png)
1223+
1224+
<Note>
1225+
Liquid blocks inside dbt YAML must be wrapped in `{% raw %}...{% endraw %}` so dbt's Jinja engine passes the template through to Lightdash untouched.
1226+
</Note>
1227+
1228+
### HTML, images, and inline styles
1229+
1230+
For richer layouts, combine inline HTML with images and `style` attributes. This example renders an avatar image alongside the name with a secondary link underneath:
1231+
1232+
<Tabs>
1233+
<Tab title="dbt v1.9 and earlier">
1234+
```yaml
1235+
columns:
1236+
- name: full_name
1237+
description: 'Customer full name'
1238+
meta:
1239+
dimension:
1240+
type: string
1241+
richText: |
1242+
{% raw %}{% if value.raw == nil %}
1243+
<span style="color: #999;">-</span>
1244+
{% else %}
1245+
<div style="display: flex; align-items: center; gap: 8px;">
1246+
<img src="https://ui-avatars.com/api/?name=${ value.formatted | url_encode }&background=random&size=32&rounded=true"
1247+
width="32" height="32"
1248+
style="border-radius: 50%;"
1249+
alt="${ value.formatted }" />
1250+
<p>
1251+
<strong style="float:left">${ value.formatted }</strong><br/>
1252+
<span style="color: #666; font-size: 0.9em;">
1253+
<a style="float:left;" href="https://www.linkedin.com/search/results/people/?keywords=${ value.formatted | url_encode }" target="_blank">LinkedIn</a>
1254+
</span>
1255+
</p>
1256+
</div>
1257+
{% endif %}{% endraw %}
1258+
```
1259+
</Tab>
1260+
<Tab title="dbt v1.10+ and Fusion">
1261+
```yaml
1262+
columns:
1263+
- name: full_name
1264+
description: 'Customer full name'
1265+
config:
1266+
meta:
1267+
dimension:
1268+
type: string
1269+
richText: |
1270+
{% raw %}{% if value.raw == nil %}
1271+
<span style="color: #999;">-</span>
1272+
{% else %}
1273+
<div style="display: flex; align-items: center; gap: 8px;">
1274+
<img src="https://ui-avatars.com/api/?name=${ value.formatted | url_encode }&background=random&size=32&rounded=true"
1275+
width="32" height="32"
1276+
style="border-radius: 50%;"
1277+
alt="${ value.formatted }" />
1278+
<p>
1279+
<strong style="float:left">${ value.formatted }</strong><br/>
1280+
<span style="color: #666; font-size: 0.9em;">
1281+
<a style="float:left;" href="https://www.linkedin.com/search/results/people/?keywords=${ value.formatted | url_encode }" target="_blank">LinkedIn</a>
1282+
</span>
1283+
</p>
1284+
</div>
1285+
{% endif %}{% endraw %}
1286+
```
1287+
</Tab>
1288+
<Tab title="Lightdash YAML">
1289+
```yaml
1290+
dimensions:
1291+
- name: full_name
1292+
description: 'Customer full name'
1293+
type: string
1294+
richText: |
1295+
{% raw %}{% if value.raw == nil %}
1296+
<span style="color: #999;">-</span>
1297+
{% else %}
1298+
<div style="display: flex; align-items: center; gap: 8px;">
1299+
<img src="https://ui-avatars.com/api/?name=${ value.formatted | url_encode }&background=random&size=32&rounded=true"
1300+
width="32" height="32"
1301+
style="border-radius: 50%;"
1302+
alt="${ value.formatted }" />
1303+
<p>
1304+
<strong style="float:left">${ value.formatted }</strong><br/>
1305+
<span style="color: #666; font-size: 0.9em;">
1306+
<a style="float:left;" href="https://www.linkedin.com/search/results/people/?keywords=${ value.formatted | url_encode }" target="_blank">LinkedIn</a>
1307+
</span>
1308+
</p>
1309+
</div>
12051310
{% endif %}{% endraw %}
12061311
```
12071312
</Tab>
12081313
</Tabs>
12091314

1315+
![Avatar image with colored initials, bold name, and a LinkedIn link rendered per row](/images/references/rich-text-html-avatars.png)
1316+
12101317
### Liquid templating in rich text
12111318

12121319
<LiquidTemplating />

0 commit comments

Comments
 (0)