Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

Normalize math rendering in docs panel and LSP tooltips (#8315)

LiquidGunay9a2490203730
diff --git a/frontend/src/core/codemirror/lsp/__tests__/normalize-markdown-math.test.ts b/frontend/src/core/codemirror/lsp/__tests__/normalize-markdown-math.test.ts
new file mode 100644
index 0000000000..6edea94cf0
--- /dev/null
+++ b/frontend/src/core/codemirror/lsp/__tests__/normalize-markdown-math.test.ts
@@ -0,0 +1,123 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { describe, expect, it } from "vitest";
+import {
+ normalizeLspDocumentation,
+ normalizeMarkdownMath,
+} from "../normalize-markdown-math";
+
+describe("normalizeMarkdownMath", () => {
+ it("converts rst math directives to marimo-tex display math", () => {
+ const markdown = `
+For t > 0:
+
+.. math::
+
+ m_t = \\beta_1 \\cdot m_{t-1}
+`.trim();
+
+ const normalized = normalizeMarkdownMath(markdown);
+ expect(normalized).not.toContain(".. math::");
+ expect(normalized).toContain("<marimo-tex");
+ expect(normalized).toContain("||[m_t = \\beta_1 \\cdot m_{t-1}||]");
+ });
+
+ it("converts :math: roles and latex delimiters", () => {
+ const markdown =
+ "Inline :math:`x^2`, \\(y^2\\), \\[z^2\\], $a^2$, and $$b^2$$.";
+
+ const normalized = normalizeMarkdownMath(markdown);
+ expect(normalized).not.toContain(":math:`");
+ expect(normalized).not.toContain("\\(");
+ expect(normalized).not.toContain("\\[");
+ expect(normalized).toContain("<marimo-tex");
+ expect(normalized).toContain("||(x^2||)");
+ expect(normalized).toContain("||(y^2||)");
+ expect(normalized).toContain("||[z^2||]");
+ expect(normalized).toContain("||(a^2||)");
+ expect(normalized).toContain("||[b^2||]");
+ });
+
+ it("converts rst math directives with same-line latex", () => {
+ const markdown =
+ ".. math::\\begin{align*} m_t &= \\beta_1 g_t \\\\ v_t &= \\beta_2 g_t^2 \\end{align*}";
+
+ const normalized = normalizeMarkdownMath(markdown);
+ expect(normalized).not.toContain(".. math::");
+ expect(normalized).toContain("<marimo-tex");
+ expect(normalized).toContain(
+ "||[\\begin{align*} m_t &= \\beta_1 g_t \\\\ v_t &= \\beta_2 g_t^2 \\end{align*}||]",
+ );
+ });
+
+ it("converts rst math directives followed by unindented latex blocks", () => {
+ const markdown = `
+.. math::
+
+\\begin{align*}
+m_t &= \\beta_1 g_t \\\\
+v_t &= \\beta_2 g_t^2
+\\end{align*}
+`.trim();
+
+ const normalized = normalizeMarkdownMath(markdown);
+ expect(normalized).not.toContain(".. math::");
+ expect(normalized).toContain("<marimo-tex");
+ expect(normalized).toContain(
+ "||[\\begin{align*}\nm_t &= \\beta_1 g_t \\\\\nv_t &= \\beta_2 g_t^2\n\\end{align*}||]",
+ );
+ });
+
+ it("does not transform fenced code blocks or inline code spans", () => {
+ const markdown = `
+\`\`\`python
+formula = ":math:\`x\`"
+directive = """
+.. math::
+
+ x^2
+"""
+\`\`\`
+
+Use \`:math:\` as text and :math:\`z\` as math.
+`.trim();
+
+ const normalized = normalizeMarkdownMath(markdown);
+
+ expect(normalized).toContain('formula = ":math:`x`"');
+ expect(normalized).toContain(".. math::");
+ expect(normalized).toContain("`:math:` as text");
+ expect(normalized).not.toContain(":math:`z`");
+ expect(normalized).toContain("||(z||)");
+ });
+});
+
+describe("normalizeLspDocumentation", () => {
+ it("normalizes markdown and plaintext math markup content", () => {
+ const markdownDoc = normalizeLspDocumentation({
+ kind: "markdown",
+ value: "Compute :math:`x^2`",
+ });
+ const plaintextMathDoc = normalizeLspDocumentation({
+ kind: "plaintext",
+ value: "Compute :math:`x^2`",
+ });
+ const plaintextDoc = normalizeLspDocumentation({
+ kind: "plaintext",
+ value: "Price is $5 today",
+ });
+
+ expect(markdownDoc).toEqual({
+ kind: "markdown",
+ value: 'Compute <marimo-tex class="arithmatex">||(x^2||)</marimo-tex>',
+ });
+ expect(plaintextMathDoc).toEqual({
+ kind: "markdown",
+ value: 'Compute <marimo-tex class="arithmatex">||(x^2||)</marimo-tex>',
+ });
+ expect(plaintextDoc).toEqual({
+ kind: "plaintext",
+ value: "Price is $5 today",
+ });
+ });
+});
diff --git a/frontend/src/core/codemirror/lsp/__tests__/notebook-lsp.test.ts b/frontend/src/core/codemirror/lsp/__tests__/notebook-lsp.test.ts
index e1d17b3c7b..1dd9d55991 100644
--- a/frontend/src/core/codemirror/lsp/__tests__/notebook-lsp.test.ts
+++ b/frontend/src/core/codemirror/lsp/__tests__/notebook-lsp.test.ts
@@ -329,6 +329,40 @@ describe("NotebookLanguageServerClient", () => {
});
});
+ it("should normalize math content in hover markdown", async () => {
+ const hoverParams: LSP.HoverParams = {
+ textDocument: { uri: "file:///cell1.py" },
+ position: { line: 0, character: 1 },
+ };
+
+ const mockHoverResponse: LSP.Hover = {
+ contents: {
+ kind: "markdown",
+ value:
+ "For t > 0:\n\n.. math::\n\n\\begin{align*}\nm_t &= \\beta_1 \\cdot g_t\n\\end{align*}",
+ },
+ };
+
+ mockClient.textDocumentHover.mockResolvedValue(mockHoverResponse);
+
+ await notebookClient.textDocumentDidOpen({
+ textDocument: {
+ uri: "file:///cell1.py",
+ languageId: "python",
+ version: 1,
+ text: "value = 1",
+ },
+ });
+
+ const result = await notebookClient.textDocumentHover(hoverParams);
+ const contents = result?.contents as LSP.MarkupContent;
+
+ expect(contents.kind).toBe("markdown");
+ expect(contents.value).toContain("<marimo-tex");
+ expect(contents.value).not.toContain(".. math::");
+ expect(contents.value).toContain("\\begin{align*}");
+ });
+
it("should return null for empty hover contents", async () => {
const hoverParams: LSP.HoverParams = {
textDocument: { uri: "file:///cell1.py" },
@@ -390,6 +424,168 @@ describe("NotebookLanguageServerClient", () => {
}),
);
});
+
+ it("should normalize completion item markdown documentation", async () => {
+ const completionParams: LSP.CompletionParams = {
+ textDocument: { uri: "file:///cell1.py" },
+ position: { line: 0, character: 4 },
+ };
+
+ const mockCompletionResponse: LSP.CompletionList = {
+ isIncomplete: false,
+ items: [
+ {
+ label: "math_completion",
+ kind: LSP.CompletionItemKind.Function,
+ documentation: {
+ kind: "markdown",
+ value: "Compute :math:`x^2`",
+ },
+ },
+ ],
+ };
+
+ mockClient.textDocumentCompletion.mockResolvedValue(
+ mockCompletionResponse,
+ );
+
+ await notebookClient.textDocumentDidOpen({
+ textDocument: {
+ uri: "file:///cell1.py",
+ languageId: "python",
+ version: 1,
+ text: "math",
+ },
+ });
+
+ const result =
+ await notebookClient.textDocumentCompletion(completionParams);
+ const completion = (result as LSP.CompletionList).items[0];
+ const documentation = completion?.documentation as LSP.MarkupContent;
+
+ expect(documentation.kind).toBe("markdown");
+ expect(documentation.value).toContain("<marimo-tex");
+ expect(documentation.value).not.toContain(":math:`");
+ });
+
+ it("should normalize completion item plaintext math documentation", async () => {
+ const completionParams: LSP.CompletionParams = {
+ textDocument: { uri: "file:///cell1.py" },
+ position: { line: 0, character: 4 },
+ };
+
+ const mockCompletionResponse: LSP.CompletionList = {
+ isIncomplete: false,
+ items: [
+ {
+ label: "math_completion_plain",
+ kind: LSP.CompletionItemKind.Function,
+ documentation: {
+ kind: "plaintext",
+ value: "For t > 0:\n\n.. math::\n\n m_t = \\beta_1 \\cdot g_t",
+ },
+ },
+ ],
+ };
+
+ mockClient.textDocumentCompletion.mockResolvedValue(
+ mockCompletionResponse,
+ );
+
+ await notebookClient.textDocumentDidOpen({
+ textDocument: {
+ uri: "file:///cell1.py",
+ languageId: "python",
+ version: 1,
+ text: "math",
+ },
+ });
+
+ const result =
+ await notebookClient.textDocumentCompletion(completionParams);
+ const completion = (result as LSP.CompletionList).items[0];
+ const documentation = completion?.documentation as LSP.MarkupContent;
+
+ expect(documentation.kind).toBe("markdown");
+ expect(documentation.value).toContain("<marimo-tex");
+ expect(documentation.value).not.toContain(".. math::");
+ });
+ });
+
+ describe("completionItemResolve", () => {
+ it("should normalize resolved completion markdown documentation", async () => {
+ const unresolvedItem: LSP.CompletionItem = { label: "test" };
+ const resolvedItem: LSP.CompletionItem = {
+ label: "test",
+ documentation: {
+ kind: "markdown",
+ value: "For t > 0:\n\n.. math::\n\n m_t = \\beta_1 \\cdot g_t",
+ },
+ };
+
+ mockClient.completionItemResolve.mockResolvedValue(resolvedItem);
+
+ const result = await notebookClient.completionItemResolve(unresolvedItem);
+ const documentation = result.documentation as LSP.MarkupContent;
+
+ expect(documentation.kind).toBe("markdown");
+ expect(documentation.value).toContain("<marimo-tex");
+ expect(documentation.value).not.toContain(".. math::");
+ });
+ });
+
+ describe("textDocumentSignatureHelp", () => {
+ it("should normalize signature and parameter markdown documentation", async () => {
+ const signatureHelpParams: LSP.SignatureHelpParams = {
+ textDocument: { uri: "file:///cell1.py" },
+ position: { line: 0, character: 3 },
+ };
+
+ const mockSignatureHelp: LSP.SignatureHelp = {
+ signatures: [
+ {
+ label: "foo(x)",
+ documentation: {
+ kind: "markdown",
+ value: "Compute :math:`x^2`",
+ },
+ parameters: [
+ {
+ label: "x",
+ documentation: {
+ kind: "markdown",
+ value:
+ "For t > 0:\n\n.. math::\n\n m_t = \\beta_1 \\cdot g_t",
+ },
+ },
+ ],
+ },
+ ],
+ };
+
+ mockClient.textDocumentSignatureHelp.mockResolvedValue(mockSignatureHelp);
+
+ await notebookClient.textDocumentDidOpen({
+ textDocument: {
+ uri: "file:///cell1.py",
+ languageId: "python",
+ version: 1,
+ text: "foo(",
+ },
+ });
+
+ const result =
+ await notebookClient.textDocumentSignatureHelp(signatureHelpParams);
+ const signature = result?.signatures[0];
+ const signatureDoc = signature?.documentation as LSP.MarkupContent;
+ const parameterDoc = signature?.parameters?.[0]
+ ?.documentation as LSP.MarkupContent;
+
+ expect(signatureDoc.value).toContain("<marimo-tex");
+ expect(signatureDoc.value).not.toContain(":math:`");
+ expect(parameterDoc.value).toContain("<marimo-tex");
+ expect(parameterDoc.value).not.toContain(".. math::");
+ });
});
describe("textDocumentRename", () => {
diff --git a/frontend/src/core/codemirror/lsp/normalize-markdown-math.ts b/frontend/src/core/codemirror/lsp/normalize-markdown-math.ts
new file mode 100644
index 0000000000..7d16229360
--- /dev/null
+++ b/frontend/src/core/codemirror/lsp/normalize-markdown-math.ts
@@ -0,0 +1,381 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type * as LSP from "vscode-languageserver-protocol";
+
+// Matches inline RST math role: :math:`...`
+const INLINE_MATH_ROLE_REGEX = /(?<!`):math:`([^\n`]+)`/g;
+// Matches role variant with HTML code tag: :math:<code>...</code>
+const INLINE_MATH_ROLE_CODE_REGEX = /:math:\s*<code>(.+?)<\/code>/gs;
+// Matches display bracket delimiters: \[...\]
+const DISPLAY_BRACKET_REGEX = /\\\[(.+?)\\]/gs;
+// Matches inline paren delimiters: \(...\)
+const INLINE_PAREN_REGEX = /\\\((.+?)\\\)/gs;
+// Matches display dollar delimiters: $$...$$
+const DISPLAY_DOLLAR_REGEX = /(?<!\\)\$\$(.+?)(?<!\\)\$\$/gs;
+// Matches inline dollar delimiters: $...$
+const INLINE_DOLLAR_REGEX = /(?<![$\\])\$(?!\$)([^\n$]+?)(?<!\\)\$(?!\$)/g;
+
+interface FencedSegment {
+ text: string;
+ isFenced: boolean;
+}
+
+interface InlineCodeSegment {
+ text: string;
+ isInlineCode: boolean;
+}
+
+/**
+ * Normalize supported math syntaxes inside markdown payloads used by LSP.
+ *
+ * The output stays markdown/HTML-compatible for the tooltip renderer while
+ * skipping fenced and inline code so examples remain literal.
+ */
+export function normalizeMarkdownMath(markdown: string): string {
+ if (!containsMathSyntax(markdown)) {
+ return markdown;
+ }
+
+ return splitByFencedCodeBlocks(markdown)
+ .map((segment) => {
+ if (segment.isFenced) {
+ return segment.text;
+ }
+
+ const withMathRolesNormalized = segment.text
+ .replaceAll(INLINE_MATH_ROLE_REGEX, (_, math) => inlineMath(math))
+ .replaceAll(INLINE_MATH_ROLE_CODE_REGEX, (_, math) => inlineMath(math));
+
+ return splitByInlineCodeSegments(withMathRolesNormalized)
+ .map((inlineSegment) => {
+ if (inlineSegment.isInlineCode) {
+ return inlineSegment.text;
+ }
+ return normalizePlainTextMath(inlineSegment.text);
+ })
+ .join("");
+ })
+ .join("");
+}
+
+/**
+ * Apply markdown math normalization across the LSP documentation union.
+ *
+ * For plaintext payloads, this only upcasts to markdown when math syntax is
+ * detected, so non-math plaintext keeps its previous behavior.
+ */
+export function normalizeLspDocumentation(
+ documentation:
+ | LSP.MarkupContent
+ | LSP.MarkedString
+ | LSP.MarkedString[]
+ | undefined,
+): LSP.MarkupContent | LSP.MarkedString | LSP.MarkedString[] | undefined {
+ if (documentation == null) {
+ return documentation;
+ }
+
+ if (Array.isArray(documentation)) {
+ return documentation.map((item) => normalizeLspMarkedString(item));
+ }
+
+ if (typeof documentation === "string") {
+ return normalizeMarkdownMath(documentation);
+ }
+
+ if (isMarkupContent(documentation)) {
+ if (documentation.kind === "markdown") {
+ return {
+ ...documentation,
+ value: normalizeMarkdownMath(documentation.value),
+ };
+ }
+
+ if (!containsMathSyntax(documentation.value)) {
+ return documentation;
+ }
+
+ return {
+ kind: "markdown",
+ value: normalizeMarkdownMath(documentation.value),
+ };
+ }
+
+ return normalizeLspMarkedString(documentation);
+}
+
+function normalizeLspMarkedString(marked: LSP.MarkedString): LSP.MarkedString {
+ if (typeof marked === "string") {
+ return normalizeMarkdownMath(marked);
+ }
+ if (marked.language !== "markdown" && marked.language !== "md") {
+ return marked;
+ }
+ return {
+ ...marked,
+ value: normalizeMarkdownMath(marked.value),
+ };
+}
+
+function isMarkupContent(
+ documentation: LSP.MarkupContent | LSP.MarkedString,
+): documentation is LSP.MarkupContent {
+ return (
+ typeof documentation === "object" &&
+ "kind" in documentation &&
+ "value" in documentation
+ );
+}
+
+function containsMathSyntax(markdown: string): boolean {
+ return (
+ markdown.includes(".. math::") ||
+ markdown.includes(":math:`") ||
+ // Detects display bracket delimiters.
+ /\\\[[\S\s]+?\\]/.test(markdown) ||
+ // Detects inline paren delimiters.
+ /\\\([\S\s]+?\\\)/.test(markdown) ||
+ // Detects display dollar delimiters.
+ /(?<!\\)\$\$[\S\s]+?(?<!\\)\$\$/.test(markdown) ||
+ // Detects inline dollar delimiters.
+ /(?<![$\\])\$(?!\$)[^\n$]+?(?<!\\)\$(?!\$)/.test(markdown) ||
+ // Detects HTML code-tag RST role variant.
+ /:math:\s*<code>[\S\s]+?<\/code>/.test(markdown)
+ );
+}
+
+function splitByFencedCodeBlocks(markdown: string): FencedSegment[] {
+ // Preserve fenced code blocks as literal text during normalization.
+ const lines = markdown.split("\n");
+ const segments: FencedSegment[] = [];
+ let current: string[] = [];
+ let inFence = false;
+ let fenceChar = "";
+ let fenceLength = 0;
+
+ const flush = (isFenced: boolean) => {
+ if (current.length === 0) {
+ return;
+ }
+ segments.push({ text: current.join("\n"), isFenced });
+ current = [];
+ };
+
+ for (const line of lines) {
+ // Matches fenced-code fence markers: ``` or ~~~ (>= 3 chars).
+ const markerMatch = line.match(/^[\t ]*(`{3,}|~{3,})/);
+ if (markerMatch) {
+ const marker = markerMatch[1];
+ const markerChar = marker[0];
+ const markerLength = marker.length;
+
+ if (!inFence) {
+ flush(false);
+ inFence = true;
+ fenceChar = markerChar;
+ fenceLength = markerLength;
+ current.push(line);
+ continue;
+ }
+
+ if (markerChar === fenceChar && markerLength >= fenceLength) {
+ current.push(line);
+ flush(true);
+ inFence = false;
+ fenceChar = "";
+ fenceLength = 0;
+ continue;
+ }
+ }
+
+ current.push(line);
+ }
+
+ flush(inFence);
+ return segments;
+}
+
+function splitByInlineCodeSegments(text: string): InlineCodeSegment[] {
+ // Preserve inline code spans (single or multi-backtick delimiters).
+ const segments: InlineCodeSegment[] = [];
+ let current = "";
+ let inInlineCode = false;
+ let delimiter = "";
+ let i = 0;
+
+ while (i < text.length) {
+ if (text[i] === "`") {
+ let j = i;
+ while (j < text.length && text[j] === "`") {
+ j += 1;
+ }
+ const ticks = text.slice(i, j);
+
+ if (inInlineCode && ticks === delimiter) {
+ current += ticks;
+ segments.push({ text: current, isInlineCode: true });
+ current = "";
+ inInlineCode = false;
+ delimiter = "";
+ i = j;
+ continue;
+ }
+
+ if (!inInlineCode) {
+ if (current) {
+ segments.push({ text: current, isInlineCode: false });
+ current = "";
+ }
+ inInlineCode = true;
+ delimiter = ticks;
+ current += ticks;
+ i = j;
+ continue;
+ }
+ }
+
+ current += text[i];
+ i += 1;
+ }
+
+ if (current) {
+ segments.push({ text: current, isInlineCode: inInlineCode });
+ }
+
+ return segments;
+}
+
+function normalizePlainTextMath(text: string): string {
+ // Convert alternate math syntaxes into marimo-tex HTML wrappers.
+ let converted = convertRstMathBlocks(text);
+ converted = converted.replaceAll(DISPLAY_BRACKET_REGEX, (_, math) =>
+ displayMath(math),
+ );
+ converted = converted.replaceAll(INLINE_PAREN_REGEX, (_, math) =>
+ inlineMath(math),
+ );
+ converted = converted.replaceAll(DISPLAY_DOLLAR_REGEX, (_, math) =>
+ displayMath(math),
+ );
+ converted = converted.replaceAll(INLINE_DOLLAR_REGEX, (_, math) =>
+ inlineMath(math),
+ );
+ return converted;
+}
+
+function countIndent(line: string): number {
+ // Matches leading whitespace used to compute visual indentation.
+ return line.match(/^[\t ]*/)?.[0].replaceAll("\t", " ").length ?? 0;
+}
+
+function convertRstMathBlocks(text: string): string {
+ // Convert ``.. math::`` directive bodies to display math wrappers.
+ const lines = text.split("\n");
+ if (lines.length === 0) {
+ return text;
+ }
+
+ const output: string[] = [];
+ let i = 0;
+ while (i < lines.length) {
+ const line = lines[i];
+ // Matches RST math directive lines: ".. math:: ..."
+ const directiveMatch = line.match(/^[\t ]*\.\.\s+math::(.*)$/);
+ if (!directiveMatch) {
+ output.push(line);
+ i += 1;
+ continue;
+ }
+
+ const inlineMath = directiveMatch[1]?.trim() ?? "";
+ const baseIndent = countIndent(line);
+ i += 1;
+
+ const mathLines: string[] = [];
+ let consumeUnindentedBlock = inlineMath.includes("\\begin");
+ if (inlineMath) {
+ mathLines.push(inlineMath);
+ } else {
+ while (i < lines.length) {
+ const currentLine = lines[i];
+ if (!currentLine.trim()) {
+ i += 1;
+ continue;
+ }
+
+ const isOptionLine =
+ countIndent(currentLine) > baseIndent &&
+ currentLine.trim().startsWith(":");
+ if (!isOptionLine) {
+ break;
+ }
+ i += 1;
+ }
+
+ if (i < lines.length) {
+ const nextLine = lines[i];
+ consumeUnindentedBlock =
+ Boolean(nextLine.trim()) &&
+ countIndent(nextLine) <= baseIndent &&
+ nextLine.trimStart().startsWith("\\");
+ }
+ }
+
+ if (consumeUnindentedBlock) {
+ while (i < lines.length && lines[i].trim()) {
+ mathLines.push(lines[i]);
+ i += 1;
+ }
+ } else {
+ while (i < lines.length) {
+ const currentLine = lines[i];
+ if (!currentLine.trim()) {
+ mathLines.push("");
+ i += 1;
+ continue;
+ }
+
+ if (countIndent(currentLine) <= baseIndent) {
+ break;
+ }
+
+ mathLines.push(currentLine);
+ i += 1;
+ }
+ }
+
+ const nonEmptyMathLines = mathLines.filter((mathLine) =>
+ Boolean(mathLine.trim()),
+ );
+ if (nonEmptyMathLines.length === 0) {
+ output.push(line);
+ continue;
+ }
+
+ const minIndent = Math.min(
+ ...nonEmptyMathLines.map((mathLine) => countIndent(mathLine)),
+ );
+ const normalizedMath = mathLines
+ .map((mathLine) => {
+ if (!mathLine) {
+ return "";
+ }
+ const stripCount = Math.min(minIndent, countIndent(mathLine));
+ return mathLine.slice(stripCount);
+ })
+ .join("\n")
+ .trim();
+
+ output.push(displayMath(normalizedMath));
+ }
+
+ return output.join("\n");
+}
+
+function inlineMath(math: string): string {
+ return `<marimo-tex class="arithmatex">||(${math.trim()}||)</marimo-tex>`;
+}
+
+function displayMath(math: string): string {
+ return `<marimo-tex class="arithmatex">||[${math.trim()}||]</marimo-tex>`;
+}
diff --git a/frontend/src/core/codemirror/lsp/notebook-lsp.ts b/frontend/src/core/codemirror/lsp/notebook-lsp.ts
index 2401c17c80..bb5a536c60 100644
--- a/frontend/src/core/codemirror/lsp/notebook-lsp.ts
+++ b/frontend/src/core/codemirror/lsp/notebook-lsp.ts
@@ -16,6 +16,7 @@ import {
updateEditorCodeFromPython,
} from "../language/utils";
import { createNotebookLens, type NotebookLens } from "./lens";
+import { normalizeLspDocumentation } from "./normalize-markdown-math";
import {
CellDocumentUri,
type ILanguageServerClient,
@@ -89,6 +90,56 @@ const defaultGetNotebookEditors = () => {
return Objects.mapValues(evs, (r) => r.current?.editorViewOrNull);
};
+function normalizeTextDocumentation(
+ documentation: string | LSP.MarkupContent | undefined,
+): string | LSP.MarkupContent | undefined {
+ const normalized = normalizeLspDocumentation(
+ documentation as LSP.MarkupContent | LSP.MarkedString | undefined,
+ );
+ if (Array.isArray(normalized)) {
+ return documentation;
+ }
+ return normalized as string | LSP.MarkupContent | undefined;
+}
+
+function normalizeCompletionItem(item: LSP.CompletionItem): LSP.CompletionItem {
+ return {
+ ...item,
+ documentation: normalizeTextDocumentation(item.documentation),
+ };
+}
+
+function normalizeCompletionResponse(
+ response: LSP.CompletionList | LSP.CompletionItem[] | null,
+): LSP.CompletionList | LSP.CompletionItem[] | null {
+ if (response == null) {
+ return null;
+ }
+ if (Array.isArray(response)) {
+ return response.map((item) => normalizeCompletionItem(item));
+ }
+ return {
+ ...response,
+ items: response.items.map((item) => normalizeCompletionItem(item)),
+ };
+}
+
+function normalizeSignatureHelpResponse(
+ response: LSP.SignatureHelp,
+): LSP.SignatureHelp {
+ return {
+ ...response,
+ signatures: response.signatures.map((signature) => ({
+ ...signature,
+ documentation: normalizeTextDocumentation(signature.documentation),
+ parameters: signature.parameters?.map((parameter) => ({
+ ...parameter,
+ documentation: normalizeTextDocumentation(parameter.documentation),
+ })),
+ })),
+ };
+}
+
export class NotebookLanguageServerClient implements ILanguageServerClient {
public readonly documentUri: LSP.DocumentUri;
private readonly client: ILanguageServerClient;
@@ -372,7 +423,7 @@ export class NotebookLanguageServerClient implements ILanguageServerClient {
return null;
}
- return response;
+ return normalizeSignatureHelpResponse(response);
}
/**
@@ -569,7 +620,9 @@ export class NotebookLanguageServerClient implements ILanguageServerClient {
return cached;
}
- const resolved = this.client.completionItemResolve(params);
+ const resolved = this.client
+ .completionItemResolve(params)
+ .then((item) => normalizeCompletionItem(item));
this.completionItemCache.set(key, resolved);
return resolved;
}
@@ -626,6 +679,8 @@ export class NotebookLanguageServerClient implements ILanguageServerClient {
value: hover.contents.value,
};
}
+ hover.contents =
+ normalizeLspDocumentation(hover.contents) ?? hover.contents;
// Empty
if (hover.contents === "") {
@@ -679,13 +734,14 @@ export class NotebookLanguageServerClient implements ILanguageServerClient {
const transformedPosition = lens.transformPosition(params.position, cellId);
- return this.client.textDocumentCompletion({
+ const response = await this.client.textDocumentCompletion({
...params,
textDocument: {
uri: this.documentUri,
},
position: transformedPosition,
});
+ return normalizeCompletionResponse(response);
}
/**
diff --git a/marimo/_output/md_extensions/display_math.py b/marimo/_output/md_extensions/display_math.py
index 97f2ff02c6..87dc6b9f1e 100644
--- a/marimo/_output/md_extensions/display_math.py
+++ b/marimo/_output/md_extensions/display_math.py
@@ -25,14 +25,81 @@ class DisplayMathPreprocessor(preprocessors.Preprocessor): # type: ignore[misc]
# Opening or closing $$ on its own line
DOLLAR_DOLLAR_PATTERN = re.compile(r"^\s*\$\$\s*$")
+ # Matches inline RST math role: :math:`...`
+ INLINE_MATH_ROLE_PATTERN = re.compile(r"(?<!`):math:`([^`\n]+)`")
+ # Matches role variant with embedded HTML code tag: :math:<code>...</code>
+ INLINE_MATH_ROLE_HTML_CODE_PATTERN = re.compile(
+ r":math:\s*<code>(.+?)</code>",
+ re.DOTALL,
+ )
+ # Matches display bracket delimiters: \[...\]
+ DISPLAY_BRACKET_PATTERN = re.compile(r"\\\[(.+?)\\\]", re.DOTALL)
+ # Matches inline paren delimiters: \(...\)
+ INLINE_PAREN_PATTERN = re.compile(r"\\\((.+?)\\\)", re.DOTALL)
+
def __init__(self, md: Markdown) -> None:
super().__init__(md)
def run(self, lines: list[str]) -> list[str]:
- # Fast path: skip processing if no $$ appears anywhere
- if not any("$$" in line for line in lines):
+ """Normalize math syntaxes before markdown parsing.
+
+ This keeps legacy/reStructuredText math forms renderable by arithmatex
+ and preserves the existing $$ block-spacing fix from #8348.
+ """
+ text = "\n".join(lines)
+ if not self._contains_math_syntax(text):
return lines
+ text = self._normalize_math_syntax(text)
+ return self._normalize_display_math_spacing(text.split("\n"))
+
+ def _contains_math_syntax(self, text: str) -> bool:
+ return (
+ "$$" in text
+ or ".. math::" in text
+ or ":math:`" in text
+ or ":math:<code>" in text
+ or "\\(" in text
+ or "\\[" in text
+ )
+
+ def _normalize_math_syntax(self, text: str) -> str:
+ """Convert supported math delimiters in non-inline-code regions.
+
+ Supported conversions:
+ - ``:math:`...``` and ``:math:<code>...</code>`` -> ``$...$``
+ - ``.. math::`` blocks -> ``$$...$$``
+ - ``\\(...\\)`` -> ``$...$``
+ - ``\\[...\\]`` -> ``$$...$$``
+ """
+ converted_segments: list[str] = []
+ for segment, is_inline_code in self._split_by_inline_code(text):
+ if is_inline_code:
+ converted_segments.append(segment)
+ continue
+
+ segment = self.INLINE_MATH_ROLE_PATTERN.sub(
+ lambda match: f"${match.group(1).strip()}$",
+ segment,
+ )
+ segment = self.INLINE_MATH_ROLE_HTML_CODE_PATTERN.sub(
+ lambda match: f"${match.group(1).strip()}$",
+ segment,
+ )
+ segment = self._convert_rst_math_blocks(segment)
+ segment = self.DISPLAY_BRACKET_PATTERN.sub(
+ lambda match: self._to_display_math(match.group(1)),
+ segment,
+ )
+ segment = self.INLINE_PAREN_PATTERN.sub(
+ lambda match: f"${match.group(1).strip()}$",
+ segment,
+ )
+ converted_segments.append(segment)
+
+ return "".join(converted_segments)
+
+ def _normalize_display_math_spacing(self, lines: list[str]) -> list[str]:
result: list[str] = []
i = 0
in_multiline = False
@@ -70,6 +137,168 @@ class DisplayMathPreprocessor(preprocessors.Preprocessor): # type: ignore[misc]
return result
+ def _split_by_inline_code(self, text: str) -> list[tuple[str, bool]]:
+ """Split text into inline-code and non-code segments.
+
+ We skip normalization in inline code segments so examples such as
+ ```:math:`x``` remain literal.
+ """
+ segments: list[tuple[str, bool]] = []
+ current: list[str] = []
+ i = 0
+ in_code = False
+ delimiter = ""
+
+ while i < len(text):
+ char = text[i]
+ if char == "`":
+ # Keep ``:math:`...``` as a role token; its backticks are not
+ # markdown inline-code delimiters.
+ if not in_code and text[max(0, i - 6) : i] == ":math:":
+ role_end = text.find("`", i + 1)
+ if role_end != -1:
+ current.append(text[i : role_end + 1])
+ i = role_end + 1
+ continue
+
+ j = i
+ while j < len(text) and text[j] == "`":
+ j += 1
+ ticks = text[i:j]
+
+ if in_code and ticks == delimiter:
+ current.append(ticks)
+ segments.append(("".join(current), True))
+ current = []
+ in_code = False
+ delimiter = ""
+ i = j
+ continue
+
+ if not in_code:
+ if current:
+ segments.append(("".join(current), False))
+ current = []
+ in_code = True
+ delimiter = ticks
+ current.append(ticks)
+ i = j
+ continue
+
+ current.append(char)
+ i += 1
+
+ if current:
+ segments.append(("".join(current), in_code))
+ return segments
+
+ def _convert_rst_math_blocks(self, text: str) -> str:
+ """Convert ``.. math::`` directives to markdown display math blocks.
+
+ Handles inline and multiline directive bodies, optional directive
+ options, and a permissive unindented LaTeX continuation case used in
+ third-party docstrings.
+ """
+ lines = text.splitlines()
+ if not lines:
+ return text
+
+ output: list[str] = []
+ i = 0
+ while i < len(lines):
+ line = lines[i]
+ # Matches RST math directive lines: ".. math:: ..."
+ directive_match = re.match(r"^([ \t]*)\.\.\s+math::(.*)$", line)
+ if directive_match is None:
+ output.append(line)
+ i += 1
+ continue
+
+ inline_math = directive_match.group(2).strip()
+ base_indent = self._count_indent(line)
+ i += 1
+
+ block_lines: list[str] = []
+ consume_unindented_block = bool(
+ inline_math and "\\begin" in inline_math
+ )
+ if inline_math:
+ block_lines.append(inline_math)
+ else:
+ while i < len(lines):
+ current_line = lines[i]
+ if not current_line.strip():
+ i += 1
+ continue
+
+ is_option_line = self._count_indent(
+ current_line
+ ) > base_indent and current_line.strip().startswith(":")
+ if is_option_line:
+ i += 1
+ continue
+ break
+
+ if i < len(lines):
+ next_line = lines[i]
+ consume_unindented_block = (
+ bool(next_line.strip())
+ and self._count_indent(next_line) <= base_indent
+ and next_line.lstrip().startswith("\\")
+ )
+
+ if consume_unindented_block:
+ while i < len(lines) and lines[i].strip():
+ block_lines.append(lines[i])
+ i += 1
+ else:
+ while i < len(lines):
+ current_line = lines[i]
+ if not current_line.strip():
+ block_lines.append("")
+ i += 1
+ continue
+ if self._count_indent(current_line) <= base_indent:
+ break
+ block_lines.append(current_line)
+ i += 1
+
+ if not any(math_line.strip() for math_line in block_lines):
+ output.append(line)
+ continue
+
+ min_indent = min(
+ self._count_indent(math_line)
+ for math_line in block_lines
+ if math_line.strip()
+ )
+ dedented_lines: list[str] = []
+ for math_line in block_lines:
+ if not math_line:
+ dedented_lines.append("")
+ continue
+ strip_chars = min(min_indent, self._count_indent(math_line))
+ dedented_lines.append(math_line[strip_chars:])
+
+ math_body = "\n".join(dedented_lines).strip("\n")
+ output.extend(("$$", math_body, "$$"))
+
+ normalized = "\n".join(output)
+ if text.endswith("\n"):
+ normalized += "\n"
+ return normalized
+
+ def _count_indent(self, line: str) -> int:
+ # Matches leading whitespace used to compute visual indentation.
+ match = re.match(r"^[ \t]*", line)
+ return len(match.group(0).expandtabs(4)) if match else 0
+
+ def _to_display_math(self, math: str) -> str:
+ math = math.strip()
+ if not math:
+ return ""
+ return f"\n\n$$\n{math}\n$$\n\n"
+
class DisplayMathExtension(Extension): # type: ignore[misc]
"""
diff --git a/marimo/_runtime/complete.py b/marimo/_runtime/complete.py
index 96e0dce2c8..50b1090e1f 100644
--- a/marimo/_runtime/complete.py
+++ b/marimo/_runtime/complete.py
@@ -3,6 +3,7 @@ from __future__ import annotations
import ast
import html
+import re
import sys
import threading
import time
@@ -68,6 +69,32 @@ DOC_CACHE_SIZE = 200
#
# We also add '/' for file path completion.
COMPLETION_TRIGGER_CHARACTERS = frozenset({".", "(", ",", "/"})
+# Matches display bracket delimiters: \[...\]
+_MATH_DISPLAY_BRACKET_PATTERN = re.compile(r"\\\[(.+?)\\\]", re.DOTALL)
+# Matches inline paren delimiters: \(...\)
+_MATH_INLINE_PAREN_PATTERN = re.compile(r"\\\((.+?)\\\)", re.DOTALL)
+# Matches display dollar delimiters: $$...$$
+_MATH_DISPLAY_DOLLAR_PATTERN = re.compile(
+ r"(?<!\\)\$\$(.+?)(?<!\\)\$\$",
+ re.DOTALL,
+)
+# Matches inline dollar delimiters: $...$
+_MATH_INLINE_DOLLAR_PATTERN = re.compile(
+ r"(?<![\\$])\$(?!\$)([^$\n]+?)(?<!\\)\$(?!\$)"
+)
+
+
+def _contains_math_syntax(text: str) -> bool:
+ """Return True when a docstring contains supported math delimiters."""
+ return (
+ ".. math::" in text
+ or ":math:`" in text
+ or ":math:<code>" in text
+ or _MATH_DISPLAY_BRACKET_PATTERN.search(text) is not None
+ or _MATH_INLINE_PAREN_PATTERN.search(text) is not None
+ or _MATH_DISPLAY_DOLLAR_PATTERN.search(text) is not None
+ or _MATH_INLINE_DOLLAR_PATTERN.search(text) is not None
+ )
@lru_cache(maxsize=DOC_CACHE_SIZE)
@@ -139,12 +166,24 @@ def _convert_docstring_to_markdown(raw_docstring: str) -> str:
if DependencyManager.docstring_to_markdown.has():
import docstring_to_markdown # type: ignore
- return as_md_html(docstring_to_markdown.convert(raw_docstring))
+ try:
+ return as_md_html(docstring_to_markdown.convert(raw_docstring))
+ except docstring_to_markdown.UnknownFormatError:
+ LOGGER.debug(
+ "docstring_to_markdown could not infer docstring format; "
+ "falling back",
+ )
# Then try our custom MarimoConverter
if doc_convert.can_convert(raw_docstring):
return as_md_html(doc_convert.convert(raw_docstring))
+ # Prefer markdown rendering when math syntax is present.
+ # This ensures ``.. math::`` and markdown delimiters are interpreted by
+ # the same TeX pipeline used elsewhere in marimo output.
+ if _contains_math_syntax(raw_docstring):
+ return as_md_html(raw_docstring)
+
# Then try RST
try:
return (
@@ -194,7 +233,7 @@ def _get_docstring(completion: jedi.api.classes.BaseName) -> str:
if raw_init:
init_docstring = (
"__init__ docstring:\n\n"
- + _md(raw_init, apply_markdown_class=False).text
+ + _convert_docstring_to_markdown(raw_init)
)
# Build final docstring
diff --git a/tests/_output/test_md.py b/tests/_output/test_md.py
index c2317551ad..b415915aac 100644
--- a/tests/_output/test_md.py
+++ b/tests/_output/test_md.py
@@ -520,11 +520,11 @@ def test_md_caret_combined() -> None:
@patch("marimo._runtime.output")
def test_latex_via_path(output: MagicMock, tmp_path: Path) -> None:
filename = tmp_path / "macros.tex"
- filename.write_text("\\newcommand{\\\foo}{bar}")
+ filename.write_text("\\newcommand{\\\\foo}{bar}")
latex(filename=filename)
assert (
output.append.call_args[0][0].text
- == '<span class="markdown prose dark:prose-invert contents"><marimo-tex class="arithmatex">||[\n\\newcommand{\\\x0coo}{bar}\n||]</marimo-tex></span>'
+ == '<span class="markdown prose dark:prose-invert contents"><marimo-tex class="arithmatex">||[\n\\newcommand{\\\\foo}{bar}\n||]</marimo-tex></span>'
)
@@ -532,13 +532,13 @@ def test_latex_via_path(output: MagicMock, tmp_path: Path) -> None:
@patch("marimo._output.md.urlopen")
def test_latex_via_url(mock_urlopen: MagicMock, output: MagicMock) -> None:
mock_response = MagicMock()
- mock_response.read.return_value = b"\\newcommand{\\\foo}{bar}"
+ mock_response.read.return_value = b"\\newcommand{\\\\foo}{bar}"
mock_urlopen.return_value.__enter__.return_value = mock_response
latex(filename="https://example.com/macros.tex")
assert (
output.append.call_args[0][0].text
- == '<span class="markdown prose dark:prose-invert contents"><marimo-tex class="arithmatex">||[\n\\newcommand{\\\foo}{bar}\n||]</marimo-tex></span>'
+ == '<span class="markdown prose dark:prose-invert contents"><marimo-tex class="arithmatex">||[\n\\newcommand{\\\\foo}{bar}\n||]</marimo-tex></span>'
)
@@ -698,6 +698,46 @@ def test_md_display_math_without_blank_lines() -> None:
assert "$$ not math" in result_code
+def test_md_normalizes_rst_math_directives() -> None:
+ result = _md(
+ "For t > 0:\n\n.. math::\n\n m_t = \\beta_1 \\cdot g_t",
+ apply_markdown_class=False,
+ ).text
+ assert ".. math::" not in result
+ assert "<marimo-tex" in result
+ assert "||[" in result
+ assert "m_t = \\beta_1 \\cdot g_t" in result
+
+
+def test_md_normalizes_math_roles_and_latex_delimiters() -> None:
+ result = _md(
+ r"Inline :math:`x^2`, :math:<code>\alpha_t</code>, \(y^2\), and \[z^2\].",
+ apply_markdown_class=False,
+ ).text
+
+ assert ":math:`" not in result
+ assert ":math:<code>" not in result
+ assert result.count("<marimo-tex") >= 4
+ assert "||(x^2||)" in result
+ assert "||(\\alpha_t||)" in result
+ assert "||(y^2||)" in result
+ assert "||[" in result
+ assert "z^2" in result
+
+
+def test_md_math_normalization_skips_fenced_and_inline_code() -> None:
+ result = _md(
+ "```\n:math:`x`\n.. math::\n```\n\nUse `:math:` as text and :math:`y`.",
+ apply_markdown_class=False,
+ ).text
+
+ assert "codehilite" in result
+ assert "<code>:math:</code>" in result
+ assert ":math:`y`" not in result
+ assert result.count("<marimo-tex") == 1
+ assert "||(y||)" in result
+
+
def test_md_display_math_format_preserved() -> None:
# __format__ should return original markdown text
text = "Hello\n$$f(x)$$\nworld"
diff --git a/tests/_runtime/test_complete.py b/tests/_runtime/test_complete.py
index abde7d9791..51c96a072f 100644
--- a/tests/_runtime/test_complete.py
+++ b/tests/_runtime/test_complete.py
@@ -19,6 +19,7 @@ from marimo._messaging.types import KernelMessage, Stream
from marimo._runtime.commands import CodeCompletionCommand
from marimo._runtime.complete import (
_build_docstring_cached,
+ _get_docstring,
_maybe_get_key_options,
_resolve_chained_key_path,
complete,
@@ -68,6 +69,169 @@ def test_docstring_function_with_google_style():
snapshot("docstrings_function_google.txt", result)
+def test_docstring_math_directive_is_normalized():
+ result = _build_docstring_cached(
+ completion_type="function",
+ completion_name="my_func",
+ signature_strings=("my_func(arg1)",),
+ raw_body=r"""
+ For :math:`t > 0`, we have:
+
+ .. math::
+
+ m_t = \beta_1 \cdot m_{t-1}
+ """,
+ init_docstring=None,
+ )
+
+ assert ".. math::" not in result
+ assert ":math:`" not in result
+ assert "<marimo-tex" in result
+ assert "m_t" in result
+
+
+def test_docstring_inline_math_directive_is_normalized():
+ result = _build_docstring_cached(
+ completion_type="function",
+ completion_name="my_func",
+ signature_strings=("my_func(arg1)",),
+ raw_body=(
+ r".. math::\begin{align*} m_t &= \beta_1 g_t "
+ r"\\ v_t &= \beta_2 g_t^2 \end{align*}"
+ ),
+ init_docstring=None,
+ )
+
+ assert ".. math::" not in result
+ assert "<marimo-tex" in result
+ assert r"\begin{align*}" in result
+
+
+def test_docstring_unindented_math_block_is_normalized():
+ result = _build_docstring_cached(
+ completion_type="function",
+ completion_name="my_func",
+ signature_strings=("my_func(arg1)",),
+ raw_body=r"""
+ .. math::
+
+ \begin{align*}
+ m_t &= \beta_1 g_t
+ \end{align*}
+ """,
+ init_docstring=None,
+ )
+
+ assert ".. math::" not in result
+ assert "<marimo-tex" in result
+ assert r"\begin{align*}" in result
+
+
+def test_docstring_inline_math_role_is_normalized():
+ result = _build_docstring_cached(
+ completion_type="function",
+ completion_name="my_func",
+ signature_strings=("my_func(arg1)",),
+ raw_body=r"""Computes :math:`\alpha + \beta`.""",
+ init_docstring=None,
+ )
+
+ assert ":math:`" not in result
+ assert "<marimo-tex" in result
+ assert r"\alpha + \beta" in result
+
+
+def test_docstring_latex_delimiters_are_normalized():
+ result = _build_docstring_cached(
+ completion_type="function",
+ completion_name="my_func",
+ signature_strings=("my_func(arg1)",),
+ raw_body=r"""Inline \(x^2\), display \[x^2 + y^2\], and $z^2$.""",
+ init_docstring=None,
+ )
+
+ assert r"\(" not in result
+ assert r"\[" not in result
+ assert "<marimo-tex" in result
+ assert result.count("<marimo-tex") >= 3
+
+
+def test_docstring_math_normalization_skips_fenced_code_blocks():
+ raw_docstring = """
+Before
+
+```python
+formula = ":math:`x`"
+directive = '''
+.. math::
+
+ x^2
+'''
+```
+
+After :math:`y`
+"""
+ result = _build_docstring_cached(
+ completion_type="function",
+ completion_name="my_func",
+ signature_strings=("my_func(arg1)",),
+ raw_body=raw_docstring,
+ init_docstring=None,
+ )
+
+ if DependencyManager.docstring_to_markdown.has():
+ # docstring_to_markdown may normalize fenced code content to $$.
+ assert "$$" in result
+ else:
+ assert ".. math::" in result
+ assert ":math:`y`" not in result
+ assert result.count("<marimo-tex") == 1
+
+
+def test_get_docstring_class_init_uses_same_math_rendering_path():
+ class _FakeSignature:
+ def to_string(self) -> str:
+ return "MyClass()"
+
+ class _FakeInit:
+ name = "__init__"
+
+ def docstring(self, raw: bool = False) -> str:
+ assert raw
+ return r"""
+ .. math::
+
+ m_t = \beta_1 \cdot g_t
+ """
+
+ class _FakeDefinition:
+ def defined_names(self) -> list[_FakeInit]:
+ return [_FakeInit()]
+
+ class _FakeCompletion:
+ type = "class"
+ name = "MyClass"
+
+ def docstring(self, raw: bool = False) -> str:
+ assert raw
+ return "Class docs."
+
+ def get_signatures(self) -> list[_FakeSignature]:
+ return [_FakeSignature()]
+
+ def goto(self) -> list[_FakeDefinition]:
+ return [_FakeDefinition()]
+
+ with mock.patch(
+ "marimo._runtime.complete.jedi.api.classes.Name", _FakeDefinition
+ ):
+ result = _get_docstring(_FakeCompletion())
+
+ assert "__init__ docstring:" in result
+ assert ".. math::" not in result
+ assert "<marimo-tex" in result
+
+
def test_build_docstring_class_with_init():
result = _build_docstring_cached(
completion_type="class",