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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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;// Emptyif (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.pyindex 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 lineDOLLAR_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 = 0in_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.pyindex 96e0dce2c8..50b1090e1f 100644--- a/marimo/_runtime/complete.py+++ b/marimo/_runtime/complete.py@@ -3,6 +3,7 @@ from __future__ import annotationsimport astimport html+import reimport sysimport threadingimport 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 MarimoConverterif 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 RSTtry: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 docstringdiff --git a/tests/_output/test_md.py b/tests/_output/test_md.pyindex 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_responselatex(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 texttext = "Hello\n$$f(x)$$\nworld"diff --git a/tests/_runtime/test_complete.py b/tests/_runtime/test_complete.pyindex 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, Streamfrom marimo._runtime.commands import CodeCompletionCommandfrom 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",