[BREAKINGCHANGE] Markdown: add option to enable HTML rendering

docs/markdown/go-sdk.md

@@ -37,6 +37,16 @@ markdown.NewLine("my super new line text")
 
 Add a new line to the markdown text.
 
+### RenderHTML
+
+```golang
+import "github.com/perses/plugins/markdown/sdk/go"
+
+markdown.RenderHTML(true)
+```
+
+Render raw HTML tags found in the markdown text. Disabled by default, in which case raw HTML is displayed as plain text.
+
 ## Example
 
 ```golang

docs/markdown/model.md

@@ -4,4 +4,12 @@
 kind: "Markdown"
 spec:
   text: <string>
+  renderHtml: <boolean> # Optional
 ```
+
+## Spec fields
+
+- `text`: the Markdown text displayed in the panel. Dashboard variables are replaced before rendering.
+- `renderHtml`: when `true`, raw HTML tags in `text` are rendered (after sanitization, which strips scripts and other
+  unsafe content). Defaults to `false`: raw HTML is then escaped and displayed as plain text, so placeholders such as
+  `<host>:<port>` are kept.

markdown/schemas/markdown.cue

@@ -15,5 +15,6 @@ package model
 
 kind: "Markdown"
 spec: close({
-	text: string
+	text:        string
+	renderHtml?: bool
 })

markdown/schemas/migrate/migrate.cue

@@ -21,11 +21,17 @@ kind: "Markdown"
 if #panel.mode != _|_ {
 	spec: {
 		text: #panel.content
+		if #panel.mode == "html" {
+			renderHtml: true
+		}
 	}
 }
 if #panel.options != _|_ {
 	spec: {
 		text: #panel.options.content
+		if #panel.options.mode != _|_ if #panel.options.mode == "html" {
+			renderHtml: true
+		}
 	}
 }
 if #panel.options == _|_ && #panel.mode == _|_ {

markdown/schemas/migrate/tests/text-markdown/expected.json

@@ -0,0 +1,6 @@
+{
+  "kind": "Markdown",
+  "spec": {
+    "text": "# Title\n\nSome **markdown** content"
+  }
+}

markdown/schemas/migrate/tests/text-markdown/input.json

@@ -0,0 +1,15 @@
+{
+  "gridPos": {
+    "h": 8,
+    "w": 12,
+    "x": 0,
+    "y": 1
+  },
+  "id": 4,
+  "options": {
+    "content": "# Title\n\nSome **markdown** content",
+    "mode": "markdown"
+  },
+  "title": "Markdown text",
+  "type": "text"
+}

markdown/schemas/migrate/tests/text/expected.json

@@ -1,6 +1,7 @@
 {
   "kind": "Markdown",
   "spec": {
-    "text": "This dashboard does have some purpose, let me remind... uuuuh..."
+    "text": "This dashboard does have some purpose, let me remind... uuuuh...",
+    "renderHtml": true
   }
 }

markdown/schemas/tests/invalid/markdown-invalid-render-html.json

@@ -0,0 +1,7 @@
+{
+  "kind": "Markdown",
+  "spec": {
+    "text": "Some text",
+    "renderHtml": "yes"
+  }
+}

markdown/schemas/tests/valid/markdown-with-html.json

@@ -0,0 +1,7 @@
+{
+  "kind": "Markdown",
+  "spec": {
+    "text": "## Some panels!\n<details><summary>More</summary>Hidden content</details>",
+    "renderHtml": true
+  }
+}

markdown/sdk/go/markdown.go

@@ -18,7 +18,8 @@ import "github.com/perses/perses/go-sdk/panel"
 const PluginKind = "Markdown"
 
 type PluginSpec struct {
-	Text string `json:"text" yaml:"text"`
+	Text       string `json:"text" yaml:"text"`
+	RenderHTML bool   `json:"renderHtml,omitempty" yaml:"renderHtml,omitempty"`
 }
 
 type Option func(plugin *Builder) error

markdown/sdk/go/options.go

@@ -28,3 +28,10 @@ func NewLine(text string) Option {
 		return nil
 	}
 }
+
+func RenderHTML(render bool) Option {
+	return func(builder *Builder) error {
+		builder.RenderHTML = render
+		return nil
+	}
+}

markdown/src/MarkdownPanel.test.ts

@@ -0,0 +1,56 @@
+// Copyright The Perses Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { describe, expect, it } from 'vitest';
+
+import { markdownToHTML, sanitizeHTML } from './MarkdownPanel';
+
+function render(text: string, renderHtml?: boolean): HTMLElement {
+  const container = document.createElement('div');
+  container.innerHTML = sanitizeHTML(markdownToHTML(text, renderHtml));
+  return container;
+}
+
+describe('markdownToHTML', () => {
+  it('escapes raw HTML by default', () => {
+    const container = render('Expected format: <host>:<port>');
+    expect(container.querySelector('p')?.textContent).toBe('Expected format: <host>:<port>');
+  });
+
+  it('escapes block-level HTML when disabled', () => {
+    const container = render('<details><summary>More</summary>Hidden</details>', false);
+    expect(container.querySelector('details')).toBeNull();
+    expect(container.textContent).toContain('<details><summary>More</summary>Hidden</details>');
+  });
+
+  it('still renders markdown when HTML is disabled', () => {
+    const container = render('**bold** `code` [link](https://example.com) <https://perses.dev>');
+    expect(container.querySelector('strong')?.textContent).toBe('bold');
+    expect(container.querySelector('code')?.textContent).toBe('code');
+    const links = container.querySelectorAll('a');
+    expect(links).toHaveLength(2);
+    expect(links[0]).toHaveAttribute('href', 'https://example.com');
+    expect(links[1]).toHaveAttribute('href', 'https://perses.dev');
+  });
+
+  it('renders raw HTML when enabled', () => {
+    const container = render('<details><summary>More</summary>Hidden</details>', true);
+    expect(container.querySelector('details summary')?.textContent).toBe('More');
+  });
+
+  it('sanitizes unsafe raw HTML when enabled', () => {
+    const container = render('<img src="x" onerror="alert(1)"><script>alert(2)</script>', true);
+    expect(container.querySelector('script')).toBeNull();
+    expect(container.querySelector('img')).not.toHaveAttribute('onerror');
+  });
+});

markdown/src/MarkdownPanel.tsx

@@ -18,7 +18,7 @@ import { useChartsTheme } from '@perses-dev/components';
 import type { PanelProps } from '@perses-dev/plugin-system';
 import { useReplaceVariablesInString } from '@perses-dev/plugin-system';
 import DOMPurify from 'dompurify';
-import { marked } from 'marked';
+import { Marked } from 'marked';
 import type { ReactElement } from 'react';
 import React, { useMemo } from 'react';
 
@@ -93,10 +93,32 @@ function createMarkdownPanelStyles(theme: Theme, chartsTheme: PersesChartsTheme)
   };
 }
 
-// Convert markdown to HTML
+const HTML_ESCAPE_MAP: Record<string, string> = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;',
+};
+
+function escapeHTML(text: string): string {
+  return text.replace(/[&<>"']/g, (char) => HTML_ESCAPE_MAP[char] ?? char);
+}
+
 // Supports original markdown and GitHub Flavored markdown
-function markdownToHTML(text: string): string {
-  return marked.parse(text, { gfm: true, async: false });
+const markdownWithHTML = new Marked({ gfm: true });
+
+// Raw HTML (block and inline) is escaped so it is displayed literally, e.g. `<host>:<port>`
+const markdownWithoutHTML = new Marked({
+  gfm: true,
+  renderer: {
+    html: ({ text }): string => escapeHTML(text),
+  },
+});
+
+export function markdownToHTML(text: string, renderHtml = false): string {
+  const parser = renderHtml ? markdownWithHTML : markdownWithoutHTML;
+  return parser.parse(text, { async: false });
 }
 
 // Prevent XSS attacks by removing the vectors for attacks
@@ -108,13 +130,16 @@ export function sanitizeHTML(html: string): string {
 
 export function MarkdownPanel(props: MarkdownPanelProps): ReactElement {
   const {
-    spec: { text },
+    spec: { text, renderHtml = false },
   } = props;
   const chartsTheme = useChartsTheme();
 
   const textAfterVariableReplacement = useReplaceVariablesInString(text);
 
-  const html = useMemo(() => markdownToHTML(textAfterVariableReplacement ?? ''), [textAfterVariableReplacement]);
+  const html = useMemo(
+    () => markdownToHTML(textAfterVariableReplacement ?? '', renderHtml),
+    [textAfterVariableReplacement, renderHtml],
+  );
   const sanitizedHTML = useMemo(() => sanitizeHTML(html), [html]);
 
   return (

markdown/src/MarkdownPanelOptionsEditor.test.tsx

@@ -0,0 +1,38 @@
+// Copyright The Perses Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { MarkdownPanelOptionsEditor } from './MarkdownPanelOptionsEditor';
+
+describe('MarkdownPanelOptionsEditor', () => {
+  it('shows HTML rendering as disabled by default', () => {
+    render(<MarkdownPanelOptionsEditor value={{ text: 'hello' }} onChange={vi.fn()} />);
+    expect(screen.getByRole('checkbox', { name: /Render HTML/i })).not.toBeChecked();
+  });
+
+  it('enables HTML rendering while keeping the text', () => {
+    const onChange = vi.fn();
+    render(<MarkdownPanelOptionsEditor value={{ text: 'hello' }} onChange={onChange} />);
+    fireEvent.click(screen.getByRole('checkbox', { name: /Render HTML/i }));
+    expect(onChange).toHaveBeenCalledWith({ text: 'hello', renderHtml: true });
+  });
+
+  it('keeps renderHtml when the text changes', () => {
+    const onChange = vi.fn();
+    render(<MarkdownPanelOptionsEditor value={{ text: 'hello', renderHtml: true }} onChange={onChange} />);
+    fireEvent.change(screen.getByRole('textbox', { name: /Text/i }), { target: { value: 'world' } });
+    expect(onChange).toHaveBeenCalledWith({ text: 'world', renderHtml: true });
+  });
+});

markdown/src/MarkdownPanelOptionsEditor.tsx

@@ -11,7 +11,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import { Link, Stack, TextField } from '@mui/material';
+import { Link, Stack, Switch, TextField } from '@mui/material';
+import { OptionsEditorControl } from '@perses-dev/components';
 import type { OptionsEditorProps } from '@perses-dev/plugin-system';
 import type { ChangeEvent, ReactElement } from 'react';
 
@@ -23,13 +24,14 @@ const MARKDOWN_GUIDE_URL = 'https://commonmark.org/help/';
 const TEXT_INPUT_NUM_ROWS = 20;
 
 export function MarkdownPanelOptionsEditor(props: MarkdownPanelOptionsEditorProps): ReactElement {
-  const {
-    onChange,
-    value: { text },
-  } = props;
+  const { onChange, value } = props;
 
-  const handleChange = (e: ChangeEvent<HTMLInputElement>): void => {
-    onChange({ text: e.target.value });
+  const handleTextChange = (e: ChangeEvent<HTMLInputElement>): void => {
+    onChange({ ...value, text: e.target.value });
+  };
+
+  const handleRenderHtmlChange = (_: ChangeEvent, checked: boolean): void => {
+    onChange({ ...value, renderHtml: checked });
   };
 
   return (
@@ -43,8 +45,13 @@ export function MarkdownPanelOptionsEditor(props: MarkdownPanelOptionsEditorProp
         multiline
         rows={TEXT_INPUT_NUM_ROWS}
         // Value
-        value={text}
-        onChange={handleChange}
+        value={value.text}
+        onChange={handleTextChange}
+      />
+      <OptionsEditorControl
+        label="Render HTML"
+        description="Render raw HTML tags found in the text. When disabled, HTML is displayed as plain text."
+        control={<Switch checked={!!value.renderHtml} onChange={handleRenderHtmlChange} />}
       />
     </Stack>
   );

markdown/src/markdown-panel-model.ts

@@ -22,6 +22,11 @@ export interface MarkdownPanelDefinition extends Definition<MarkdownPanelOptions
 
 export interface MarkdownPanelOptions {
   text: string;
+  /**
+   * When true, raw HTML in the text is rendered (after sanitization).
+   * When false or omitted, raw HTML is escaped and displayed as plain text.
+   */
+  renderHtml?: boolean;
 }
 
 export function createInitialMarkdownPanelOptions(): MarkdownPanelOptions {