Skip to content

Commit 793fe19

Browse files
authored
feat: Substitute variables in markdown tiles (#3246)
## Summary This PR extends variable substitution to markdown tiles. By default, variables are substituted using the new `markdown` format, which escapes values for markdown. Invalid references are flagged, and MCP validation/prompts have been updated. Security: By default, variable values are markdown-escaped, and markdown tiles already block scripts and raw HTML, so no XSS can occur. Users can opt out of escaping (for example, in markdown code blocks) by using a non-markdown variable from (eg. `${var:csv}`). ### Screenshots or video <img width="892" height="424" alt="Screenshot 2026-09-29 at 3 30 08 PM" src="https://github.com/user-attachments/assets/bd60f775-322b-4cf7-a125-e6d39ceaba1e" /> ### How to test on Vercel preview - Create a dashboard - Add a variable - Reference the variable in a Markdown tile ### References - Linear Issue: Closes HDX-5508 - Related PRs:
1 parent fb2aebc commit 793fe19

14 files changed

Lines changed: 512 additions & 50 deletions

File tree

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
'@hyperdx/common-utils': patch
3+
'@hyperdx/app': patch
4+
'@hyperdx/api': patch
5+
---
6+
7+
feat: Substitute dashboard variables in markdown tiles

‎packages/api/src/mcp/__tests__/dashboards/validation.test.ts‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -790,19 +790,19 @@ describe('getTileVariableWarnings', () => {
790790
expect(warnings.join('\n')).toContain('(none)');
791791
});
792792

793-
it('ignores markdown tiles, which have no expressions to check', () => {
793+
it('warns about an unknown variable in a markdown tile', () => {
794794
const markdownTile: ExternalDashboardTileWithId = {
795795
id: 'md',
796796
x: 0,
797797
y: 0,
798798
w: 12,
799799
h: 3,
800800
name: 'Notes',
801-
config: { displayType: 'markdown', markdown: 'Pick a $service' },
801+
config: { displayType: 'markdown', markdown: '# $service on $env' },
802802
};
803-
expect(getTileVariableWarnings([markdownTile], [variableFilter])).toEqual(
804-
[],
805-
);
803+
expect(getTileVariableWarnings([markdownTile], [variableFilter])).toEqual([
804+
'Tile "Notes": The markdown references unknown variable $env. Available variables: service.',
805+
]);
806806
});
807807
});
808808

‎packages/api/src/mcp/prompts/dashboards/content.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -991,7 +991,7 @@ For configType: "sql" tiles, write ClickHouse SQL with template macros:
991991
table 1 to 20 select items. Optional groupBy defines row groups. Per-series numberFormat lets one column render as a duration while a sibling count column stays a plain number.
992992
heatmap Exactly 1 select item with a non-empty valueExpression. No aggFn or alias on the select item (the chart-level displayType: "heatmap" is the discriminator). Trace sources only (no Log/Metric/Session). No groupBy. Optional where filter applied before bucketing.
993993
search No select items (select is a column list string). where is the filter.
994-
markdown No select items. Set markdown field with content.
994+
markdown No select items. Set markdown field with content, which may reference dashboard variables (see DASHBOARD VARIABLES).
995995
996996
== METRIC SOURCES ==
997997
@@ -1221,6 +1221,7 @@ Only add one when the default is wrong. \${service:sqlstring} is redundant in a
12211221
lucene ("a" OR "b") ("") the default in Lucene inputs; ("") is a match-all, so no guard is needed
12221222
regex (a|b) .* use with match()
12231223
csv a,b <empty> use INSIDE a string literal
1224+
markdown a, b <empty> the default in markdown tiles; markdown syntax in values is escaped
12241225
12251226
BUILDER TILES
12261227
@@ -1234,6 +1235,11 @@ In a LUCENE input the macros have no meaning and are matched as literal text. Re
12341235
select: [{ aggFn: "count", whereLanguage: "lucene", where: "ServiceName:$service" }]
12351236
When in doubt on a variable-driven tile, set whereLanguage: "sql" and use $__filter.
12361237
1238+
MARKDOWN TILES
1239+
1240+
The markdown field substitutes $variableName / \${variableName} / \${variableName:format} with the selected values as plain text, so a note can name what the dashboard is scoped to. Nothing is selected on a freshly-opened dashboard, so the reference renders as nothing until the user picks a value; write the surrounding text so it still reads. The macros have no meaning here and are left as written.
1241+
markdown: "Latency for the selected services: $service"
1242+
12371243
RAW SQL TILES (for advanced use-cases only)
12381244
12391245
SELECT $__timeInterval(Timestamp) AS ts, count() AS errors

‎packages/api/src/mcp/tools/dashboards/validation.ts‎

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,11 @@ import {
1818
DisplayType,
1919
QueryExpressionDashboardFilter,
2020
SavedChartConfig,
21-
SearchConditionLanguage,
2221
} from '@hyperdx/common-utils/dist/types';
2322
import {
2423
getVariableReferences,
2524
mapBuilderVariableTemplates,
25+
TemplateLanguage,
2626
validateVariableReferencesInTemplate,
2727
} from '@hyperdx/common-utils/dist/variables';
2828

@@ -244,6 +244,19 @@ export function getFilterVariableWarnings(
244244
return warnings;
245245
}
246246

247+
function variableIssueSubject(language: TemplateLanguage): string {
248+
switch (language) {
249+
case 'sql':
250+
return 'SQL';
251+
case 'lucene':
252+
return 'The Lucene filter';
253+
case 'promql':
254+
return 'The PromQL expression';
255+
case 'markdown':
256+
return 'The markdown';
257+
}
258+
}
259+
247260
/**
248261
* Non-blocking checks on the dashboard variables a tile's expressions
249262
* reference, run against the variables the dashboard's filters actually
@@ -273,9 +286,9 @@ export function getTileVariableWarnings(
273286
}
274287

275288
const issues: string[] = [];
276-
const validate = (template: string, language: SearchConditionLanguage) => {
289+
const validate = (template: string, language: TemplateLanguage) => {
277290
const result = validateVariableReferencesInTemplate(template, variables, {
278-
subject: language === 'lucene' ? 'The Lucene filter' : 'SQL',
291+
subject: variableIssueSubject(language),
279292
language,
280293
});
281294
issues.push(...result.errors, ...result.warnings);
@@ -285,8 +298,10 @@ export function getTileVariableWarnings(
285298
validate(config.sqlTemplate, 'sql');
286299
} else if (
287300
isBuilderSavedChartConfig(config) &&
288-
config.displayType !== DisplayType.Markdown
301+
config.displayType === DisplayType.Markdown
289302
) {
303+
if (config.markdown) validate(config.markdown, 'markdown');
304+
} else if (isBuilderSavedChartConfig(config)) {
290305
mapBuilderVariableTemplates(config, (template, language) => {
291306
validate(template, language);
292307
return template;

‎packages/app/src/DBDashboardPage.tsx‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -596,6 +596,21 @@ const Tile = ({
596596
[serializedTileVariables],
597597
);
598598

599+
// Serialized for the same reason as `tileVariables`. Markdown tiles flag
600+
// references to names outside this list, which `tileVariables` filters out.
601+
const serializedVariableNames = useMemo(
602+
() =>
603+
variables
604+
? JSON.stringify(variables.map(variable => variable.name))
605+
: undefined,
606+
[variables],
607+
);
608+
const variableNames = useMemo<string[] | undefined>(
609+
() =>
610+
serializedVariableNames ? JSON.parse(serializedVariableNames) : undefined,
611+
[serializedVariableNames],
612+
);
613+
599614
// Serialized for the same reason as `tileVariables`: any change to the
600615
// dashboard's filters hands this tile a new array, and only a change to the
601616
// names this tile is blocked on should churn the render memo below.
@@ -1377,6 +1392,8 @@ const Tile = ({
13771392
title={title}
13781393
toolbarItems={toolbar}
13791394
config={effectiveMarkdownConfig}
1395+
variables={tileVariables}
1396+
availableVariableNames={variableNames}
13801397
/>
13811398
)}
13821399
{effectiveQueriedConfig?.displayType === DisplayType.Search &&
@@ -1495,6 +1512,8 @@ const Tile = ({
14951512
annotations,
14961513
isLive,
14971514
readOnly,
1515+
tileVariables,
1516+
variableNames,
14981517
],
14991518
);
15001519

‎packages/app/src/HDXMarkdownChart.tsx‎

Lines changed: 57 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,82 @@
1-
import { memo } from 'react';
1+
import { memo, useMemo } from 'react';
22
import ReactMarkdown from 'react-markdown';
3+
import { ChartVariable } from '@hyperdx/common-utils/dist/types';
4+
import {
5+
substituteVariables,
6+
validateVariableReferencesInTemplate,
7+
} from '@hyperdx/common-utils/dist/variables';
38

49
import ChartContainer from './components/charts/ChartContainer';
10+
import {
11+
hasVariableIssues,
12+
VariableIssueIndicator,
13+
} from './components/SQLEditor/variableValidation';
514

615
const HDXMarkdownChart = memo(
716
({
817
config: { markdown },
918
title,
1019
toolbarItems,
20+
variables: referencedVariables,
21+
availableVariableNames,
1122
}: {
1223
title?: React.ReactNode;
1324
toolbarItems?: React.ReactNode[];
1425
config: {
1526
markdown?: string;
1627
};
28+
/** The variables to substitute. Limited to the ones this chart references. */
29+
variables?: ChartVariable[];
30+
/** Every variable name in scope, for flagging unknown references. */
31+
availableVariableNames?: string[];
1732
}) => {
33+
const content = useMemo(() => {
34+
if (!markdown || referencedVariables == null) return markdown ?? '';
35+
try {
36+
return substituteVariables(markdown, {
37+
variables: referencedVariables,
38+
inputLanguage: 'markdown',
39+
});
40+
} catch {
41+
// An unknown `${name:format}` throws; show the markdown as written.
42+
return markdown;
43+
}
44+
}, [markdown, referencedVariables]);
45+
46+
const toolbar = useMemo(() => {
47+
const names =
48+
availableVariableNames ??
49+
referencedVariables?.map(variable => variable.name);
50+
51+
// Without variables in scope nothing is substituted, so a `$word` is prose.
52+
if (!markdown || !names?.length) return toolbarItems;
53+
54+
// Only names are checked for markdown, so the selections don't matter.
55+
const allVariables = names.map(name => ({ name, values: [] }));
56+
const issues = validateVariableReferencesInTemplate(
57+
markdown,
58+
allVariables,
59+
{
60+
subject: 'Markdown',
61+
language: 'markdown',
62+
},
63+
);
64+
if (!hasVariableIssues(issues)) return toolbarItems;
65+
66+
return [
67+
<VariableIssueIndicator key="variable-issues" issues={issues} />,
68+
...(toolbarItems ?? []),
69+
];
70+
}, [markdown, availableVariableNames, referencedVariables, toolbarItems]);
71+
1872
return (
1973
<ChartContainer
2074
title={title}
21-
toolbarItems={toolbarItems}
75+
toolbarItems={toolbar}
2276
disableReactiveContainer
2377
>
2478
<div className="hdx-markdown">
25-
<ReactMarkdown>{markdown ?? ''}</ReactMarkdown>
79+
<ReactMarkdown>{content}</ReactMarkdown>
2680
</div>
2781
</ChartContainer>
2882
);
Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
import React from 'react';
2+
import { screen } from '@testing-library/react';
3+
4+
import HDXMarkdownChart from '@/HDXMarkdownChart';
5+
6+
const service = { name: 'service', values: ['api', 'web'] };
7+
8+
describe('HDXMarkdownChart', () => {
9+
it('substitutes variable references', () => {
10+
renderWithMantine(
11+
<HDXMarkdownChart
12+
config={{ markdown: '# Services: $service' }}
13+
variables={[service]}
14+
/>,
15+
);
16+
expect(screen.getByText('# Services: api, web')).toBeInTheDocument();
17+
});
18+
19+
it('renders the markdown as written without variables', () => {
20+
renderWithMantine(
21+
<HDXMarkdownChart config={{ markdown: '# Services: $service' }} />,
22+
);
23+
expect(screen.getByText('# Services: $service')).toBeInTheDocument();
24+
});
25+
26+
it('renders the markdown as written when a format is unknown', () => {
27+
renderWithMantine(
28+
<HDXMarkdownChart
29+
config={{ markdown: '${service:nope}' }}
30+
variables={[service]}
31+
/>,
32+
);
33+
expect(screen.getByText('${service:nope}')).toBeInTheDocument();
34+
});
35+
36+
it('flags a reference to an unknown variable', () => {
37+
renderWithMantine(
38+
<HDXMarkdownChart
39+
config={{ markdown: '$service $nope' }}
40+
variables={[service]}
41+
/>,
42+
);
43+
expect(screen.getByTestId('variable-validation')).toHaveAccessibleName(
44+
'Markdown references unknown variable $nope. Available variables: service.',
45+
);
46+
});
47+
48+
it('checks references against the available names when given', () => {
49+
renderWithMantine(
50+
<HDXMarkdownChart
51+
config={{ markdown: '$service $env' }}
52+
variables={[service]}
53+
availableVariableNames={['service', 'env']}
54+
/>,
55+
);
56+
expect(screen.queryByTestId('variable-validation')).not.toBeInTheDocument();
57+
});
58+
59+
it('flags nothing when every reference is known', () => {
60+
renderWithMantine(
61+
<HDXMarkdownChart
62+
config={{ markdown: '$service' }}
63+
variables={[service]}
64+
/>,
65+
);
66+
expect(screen.queryByTestId('variable-validation')).not.toBeInTheDocument();
67+
});
68+
69+
it('flags nothing without variables', () => {
70+
renderWithMantine(<HDXMarkdownChart config={{ markdown: '$nope' }} />);
71+
expect(screen.queryByTestId('variable-validation')).not.toBeInTheDocument();
72+
});
73+
});

‎packages/app/src/components/DBEditTimeChartForm/EditTimeChartForm.tsx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1090,6 +1090,7 @@ export default function EditTimeChartForm({
10901090
config={{
10911091
markdown: markdown || 'Preview',
10921092
}}
1093+
variables={variables}
10931094
/>
10941095
</Box>
10951096
</div>

‎packages/app/src/components/SQLEditor/__tests__/promqlVariableCompletions.test.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,11 +65,12 @@ describe('buildPromqlVariableCompletions', () => {
6565
expect(labels([SERVICE])).not.toContain('$__filter($service)');
6666
});
6767

68-
it('withholds the formats that emit SQL or Lucene syntax', () => {
68+
it('withholds the formats that emit SQL, Lucene, or markdown syntax', () => {
6969
// Still honoured if hand-typed — just never suggested, because neither
7070
// `'api', 'web'` nor `("api" OR "web")` parses inside a PromQL expression.
7171
expect(labels([SERVICE])).not.toContain('${service:sqlstring}');
7272
expect(labels([SERVICE])).not.toContain('${service:lucene}');
73+
expect(labels([SERVICE])).not.toContain('${service:markdown}');
7374
});
7475

7576
it('offers the same set of forms for every variable', () => {

‎packages/app/src/components/SQLEditor/__tests__/variableCompletions.test.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,10 @@ describe('buildSqlVariableCompletions', () => {
5353
);
5454
});
5555

56+
it('withholds the markdown format, which only applies to markdown tiles', () => {
57+
expect(labels([SERVICE])).not.toContain('${service:markdown}');
58+
});
59+
5660
it('withholds the macros that a chart builder input never expands', () => {
5761
// Only the variable macros are substituted into builder expressions, so
5862
// offering $__timeFilter and friends here would suggest SQL that reaches

0 commit comments

Comments
 (0)