From d795bae94dfd31c14ae5a30d25a99f15d7a84102 Mon Sep 17 00:00:00 2001
From: Ridge Kimani <ridgekimani@outlook.com>
Date: Fri, 16 Oct 2026 03:26:57 -0400
Subject: [PATCH] math: render bare display environments

Sphinx emits environments such as align* inside <div class="math">
without the \[...\] delimiters, since MathJax treats them as display
math on its own. Render those nodes as display math too; KaTeX
supports align, align*, gather and the other environments MathJax
accepts outside delimiters.

Found on the NumPy "code explanations" page of the developer guide.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 lib/docs/filters/core/math.rb           | 9 +++++++--
 test/lib/docs/filters/core/math_test.rb | 8 ++++++++
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/lib/docs/filters/core/math.rb b/lib/docs/filters/core/math.rb
index e7d3b03b15..5aff68a72d 100644
--- a/lib/docs/filters/core/math.rb
+++ b/lib/docs/filters/core/math.rb
@@ -4,15 +4,20 @@ module Docs
   # Replaces Sphinx/MathJax math markup with native MathML, rendered at
   # scrape time by MathRenderer (KaTeX):
   # <span class="math">\(...\)</span> and <div class="math">\[...\]</div>
+  # Display environments such as align* are emitted without delimiters.
   class MathFilter < Filter
     TEX_DELIMITERS_RGX = /\\\((.*?)\\\)|\\\[(.*?)\\\]/m
+    TEX_ENVIRONMENT_RGX = /\A\s*\\begin\{(\w+\*?)\}.*\\end\{\1\}\s*\z/m
 
     def call
       items = css('span.math', 'div.math').filter_map do |node|
         node.css('.eqno').remove
         content = node.content
-        next unless content =~ TEX_DELIMITERS_RGX
-        [node, split(content)]
+        if content =~ TEX_DELIMITERS_RGX
+          [node, split(content)]
+        elsif content =~ TEX_ENVIRONMENT_RGX
+          [node, [[content.strip, true]]]
+        end
       end
       render(items)
       doc
diff --git a/test/lib/docs/filters/core/math_test.rb b/test/lib/docs/filters/core/math_test.rb
index d5b1f6d086..f790aef51a 100644
--- a/test/lib/docs/filters/core/math_test.rb
+++ b/test/lib/docs/filters/core/math_test.rb
@@ -52,6 +52,14 @@ def tex_of(node)
       assert_match %r{\Asee <math.+</math> and <math.+</math>\z}, filter_output_string
     end
 
+    it "renders a bare environment as display math" do
+      @body = %(<div class="math notranslate nohighlight">\n\\begin{align*} a &amp;= b \\\\ c &amp;= d \\end{align*}</div>)
+      assert_equal 1, math_nodes.length
+      assert_equal 'block', math_nodes.first['display']
+      assert_equal '\begin{align*} a &= b \\\\ c &= d \end{align*}', tex_of(math_nodes.first)
+      assert_includes math_nodes.first.to_s, '<mtable'
+    end
+
     it "keeps the equation id and drops the equation number" do
       @body = '<div class="math" id="equation-foo"><span class="eqno">(1)<a class="headerlink" href="#equation-foo">¶</a></span>\[a\]</div>'
       assert_equal 'equation-foo', math_nodes.first['id']