feat: support math expressions

dotnet · Apr 6, 2023 · 3768289 · 3768289
1 parent e956308
commit 3768289
Show file tree

Hide file tree

Showing 7 changed files with 65 additions and 5 deletions.
diff --git a/docs/docs/markdown.md b/docs/docs/markdown.md
@@ -103,6 +103,33 @@ This will be rendered as:
 
 ![alt-text](https://learn.microsoft.com/en-us/media/learn/not-found/learn-not-found-light-mode.png?branch=main)
 
+## Math Expressions
+
+Docfx supports [LaTeX formatted math expressions](https://en.wikibooks.org/wiki/LaTeX/Mathematics) within markdown using [MathJax](https://docs.mathjax.org/en/latest/#).
+
+> [!NOTE]
+> Math expressions is only supported in the `modern` template.
+
+To include a math expression inline with your text, delimit the expression with a dollar symbol $.
+
+```md
+This sentence uses `$` delimiters to show math inline:  $\sqrt{3x-1}+(1+x)^2$
+```
+
+This sentence uses `$` delimiters to show math inline:  $\sqrt{3x-1}+(1+x)^2$
+
+To add a math expression as a block, start a new line and delimit the expression with two dollar symbols $$.
+
+```md
+**The Cauchy-Schwarz Inequality**
+
+$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
+```
+
+**The Cauchy-Schwarz Inequality**
+
+$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
+
 ## Include Markdown Files
 
 Where markdown files need to be repeated in multiple articles, you can use an include file. The includes feature replace the reference with the contents of the included file at build time.

diff --git a/samples/seed/articles/markdown.md b/samples/seed/articles/markdown.md
@@ -140,6 +140,18 @@ The example highlights lines 2, line 5 to 7 and lines 9 to the end of the file.
 
 [!code-csharp[](media/Program.cs?highlight=2,5-7,9-)]
 
+## Math Expressions
+
+This sentence uses `$` delimiters to show math inline:  $\sqrt{3x-1}+(1+x)^2$
+
+**The Cauchy-Schwarz Inequality**
+
+$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
+
+This expression uses `\$` to display a dollar sign: $\sqrt{\$4}$
+
+To split <span>$</span>100 in half, we calculate $100/2$
+
 ## Tabs
 
 Tabs enable content that is multi-faceted. They allow sections of a document to contain variant content renderings and eliminates duplicate content.

diff --git a/src/Microsoft.DocAsCode.MarkdigEngine.Extensions/MarkdownExtensions.cs b/src/Microsoft.DocAsCode.MarkdigEngine.Extensions/MarkdownExtensions.cs
@@ -14,7 +14,7 @@ public static class MarkdownExtensions
     public static MarkdownPipelineBuilder UseDocfxExtensions(this MarkdownPipelineBuilder pipeline, MarkdownContext context)
     {
         return pipeline
-            //.UseMathematics()
+            .UseMathematics()
             .UseEmphasisExtras(EmphasisExtraOptions.Strikethrough)
             .UseAutoIdentifiers(AutoIdentifierOptions.GitHub)
             .UseMediaLinks()

diff --git a/templates/modern/layout/_master.tmpl b/templates/modern/layout/_master.tmpl
@@ -25,13 +25,21 @@
       {{#_enableSearch}}<meta name="docfx:rel" content="{{_rel}}">{{/_enableSearch}}
       {{#docurl}}<meta name="docfx:docurl" content="{{docurl}}">{{/docurl}}
 
+      <script>
+        MathJax = {
+          options: {
+            processHtmlClass: ['tex2jax_process', 'math']
+          }
+        };
+      </script>
+
       <script type="text/javascript" src="{{_rel}}styles/docfx.min.js"></script>
       <script type="text/javascript" src="{{_rel}}styles/main.js"></script>
     {{/redirect_url}}
   </head>
 
   {{^redirect_url}}
-  <body data-layout="{{layout}}" data-yaml-mime="{{yamlmime}}">
+  <body class="tex2jax_ignore" data-layout="{{layout}}" data-yaml-mime="{{yamlmime}}">
     <header class="bg-body border-bottom">
       <nav id="autocollapse" class="navbar navbar-expand-md" role="navigation">
         <div class="container-xxl flex-nowrap">

diff --git a/templates/modern/src/docfx.ts b/templates/modern/src/docfx.ts
@@ -10,14 +10,15 @@ import { renderBreadcrumb, renderFooter, renderInThisArticle, renderNavbar } fro
 
 import 'bootstrap-icons/font/bootstrap-icons.scss'
 import './docfx.scss'
+import 'mathjax/es5/tex-svg-full.js'
 
 declare global {
   interface Window {
     docfx: {
       ready?: boolean,
       searchReady?: boolean,
       searchResultReady?: boolean,
-    };
+    }
   }
 }
 

diff --git a/templates/package-lock.json b/templates/package-lock.json
diff --git a/templates/package.json b/templates/package.json
@@ -32,7 +32,8 @@
     "bootstrap-icons": "^1.10.3",
     "highlight.js": "^11.7.0",
     "lit-html": "^2.7.0",
-    "lunr": "2.3.9"
+    "lunr": "2.3.9",
+    "mathjax": "^3.2.2"
   },
   "devDependencies": {
     "@types/jest": "^29.5.0",