feat: support math expressions (dotnet#8600)

ErpNetDocs · Jun 28, 2024 · a8850c2 · a8850c2
1 parent bfa90c5
commit a8850c2
Show file tree

Hide file tree

Showing 20 changed files with 1,580 additions and 42 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",

diff --git a/test/docfx.Snapshot.Tests/SamplesTest.Seed/articles/markdown.html.view.verified.json b/test/docfx.Snapshot.Tests/SamplesTest.Seed/articles/markdown.html.view.verified.json
diff --git a/test/docfx.Snapshot.Tests/SamplesTest.Seed/index.verified.json b/test/docfx.Snapshot.Tests/SamplesTest.Seed/index.verified.json
@@ -217,7 +217,7 @@
   "articles/markdown.html": {
     "href": "articles/markdown.html",
     "title": "Markdown | docfx seed website",
-    "keywords": "Markdown Markdown is a lightweight markup language with plain text formatting syntax. Docfx supports CommonMark compliant Markdown parsed through the Markdig parsing engine. Markdown Extensions Docfx supports additional markdown syntax that provide richer content. These syntax are specific to docfx and won't be rendered elsewhere like GitHub. To use a custom markdown extension: Use docfx as a NuGet library: <PackageReference Include=\"Microsoft.DocAsCode.App\" Version=\"2.61.0\" /> Configure the markdig markdown pipeline: var options = new BuildOptions { // Enable custom markdown extensions here ConfigureMarkdig = pipeline => pipeline.UseCitations(), } await Docset.Build(\"docfx.json\", options); Here is a list of markdown extensions provided by docfx by default. Alerts Alerts are block quotes that render with colors and icons that indicate the significance of the content. The following alert types are supported: > [!NOTE] > Information the user should notice even if skimming. > [!TIP] > Optional information to help a user be more successful. > [!IMPORTANT] > Essential information required for user success. > [!CAUTION] > Negative potential consequences of an action. > [!WARNING] > Dangerous certain consequences of an action. They look like this in rendered page: Note Information the user should notice even if skimming. Tip Optional information to help a user be more successful. Important Essential information required for user success. Caution Negative potential consequences of an action. Warning Dangerous certain consequences of an action. Image You can embed a image in your page by using the following Markdown syntax: ![ <alt-text> ]( <image-link> ) Example: ![alt-text](https://learn.microsoft.com/en-us/media/learn/not-found/learn-not-found-light-mode.png?branch=main) This will be rendered as: 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. You can reuse a common text snippet within a sentence using inline include: Text before [!INCLUDE [<title>](<filepath>)] and after. Or reuse an entire Markdown file as a block, nested within a section of an article. Block include is on its own line: [!INCLUDE [<title>](<filepath>)] Where <title> is the name of the file and <filepath> is the relative path to the file. Included markdown files needs to be excluded from build, they are usually placed in the /includes folder. Code Snippet There are several ways to include code in an article. The code snippet syntax replaces code from another file: [!code-csharp[](Program.cs)] You can include selected lines from the code snippet using region or line range syntax: [!code-csharp[](Program.cs#region)] [!code-csharp[](Program.cs#L12-L16)] Code snippets are indicated by using a specific link syntax described as follows: [!code-<language>[](<filepath><query-options>)] Where <language> is the syntax highlighting language of the code and <filepath> is the relative path to the markdown file. Highlight Selected Lines Code Snippets typically include more code than necessary in order to provide context. It helps readability when you highlight the key lines that you're focusing on. To highlight key lines, use the highlight query options: [!code-csharp[](Program.cs?highlight=2,5-7,9-)] The example highlights lines 2, line 5 to 7 and lines 9 to the end of the file. using System; using Azure; using Azure.Storage; using Azure.Storage.Blobs; class Program { static void Main(string[] args) { // Define the connection string for the storage account string connectionString = \"DefaultEndpointsProtocol=https;AccountName=<your-account-name>;AccountKey=<your-account-key>;EndpointSuffix=core.windows.net\"; // Create a new BlobServiceClient using the connection string var blobServiceClient = new BlobServiceClient(connectionString); // Create a new container var container = blobServiceClient.CreateBlobContainer(\"mycontainer\"); // Upload a file to the container using (var fileStream = File.OpenRead(\"path/to/file.txt\")) { container.UploadBlob(\"file.txt\", fileStream); } // Download the file from the container var downloadedBlob = container.GetBlobClient(\"file.txt\").Download(); using (var fileStream = File.OpenWrite(\"path/to/downloaded-file.txt\")) { downloadedBlob.Value.Content.CopyTo(fileStream); } } } Tabs Tabs enable content that is multi-faceted. They allow sections of a document to contain variant content renderings and eliminates duplicate content. Here's an example of the tab experience: Linux Windows Content for Linux... Content for Windows... The above tab group was created with the following syntax: # [Linux](#tab/linux) Content for Linux... # [Windows](#tab/windows) Content for Windows... --- Tabs are indicated by using a specific link syntax within a Markdown header. The syntax can be described as follows: # [Tab Display Name](#tab/tab-id) A tab starts with a Markdown header, #, and is followed by a Markdown link [](). The text of the link will become the text of the tab header, displayed to the customer. In order for the header to be recognized as a tab, the link itself must start with #tab/ and be followed by an ID representing the content of the tab. The ID is used to sync all same-ID tabs across the page. Using the above example, when a user selects a tab with the link #tab/windows, all tabs with the link #tab/windows on the page will be selected. Dependent tabs It's possible to make the selection in one set of tabs dependent on the selection in another set of tabs. Here's an example of that in action: .NET .NET TypeScript TypeScript REST API .NET content for Linux... .NET content for Windows... TypeScript content for Linux... TypeScript content for Windows... REST API content, independent of platform... Notice how changing the Linux/Windows selection above changes the content in the .NET and TypeScript tabs. This is because the tab group defines two versions for each .NET and TypeScript, where the Windows/Linux selection above determines which version is shown for .NET/TypeScript. Here's the markup that shows how this is done: # [.NET](#tab/dotnet/linux) .NET content for Linux... # [.NET](#tab/dotnet/windows) .NET content for Windows... # [TypeScript](#tab/typescript/linux) TypeScript content for Linux... # [TypeScript](#tab/typescript/windows) TypeScript content for Windows... # [REST API](#tab/rest) REST API content, independent of platform... ---"
+    "keywords": "Markdown Markdown is a lightweight markup language with plain text formatting syntax. Docfx supports CommonMark compliant Markdown parsed through the Markdig parsing engine. Markdown Extensions Docfx supports additional markdown syntax that provide richer content. These syntax are specific to docfx and won't be rendered elsewhere like GitHub. To use a custom markdown extension: Use docfx as a NuGet library: <PackageReference Include=\"Microsoft.DocAsCode.App\" Version=\"2.61.0\" /> Configure the markdig markdown pipeline: var options = new BuildOptions { // Enable custom markdown extensions here ConfigureMarkdig = pipeline => pipeline.UseCitations(), } await Docset.Build(\"docfx.json\", options); Here is a list of markdown extensions provided by docfx by default. Alerts Alerts are block quotes that render with colors and icons that indicate the significance of the content. The following alert types are supported: > [!NOTE] > Information the user should notice even if skimming. > [!TIP] > Optional information to help a user be more successful. > [!IMPORTANT] > Essential information required for user success. > [!CAUTION] > Negative potential consequences of an action. > [!WARNING] > Dangerous certain consequences of an action. They look like this in rendered page: Note Information the user should notice even if skimming. Tip Optional information to help a user be more successful. Important Essential information required for user success. Caution Negative potential consequences of an action. Warning Dangerous certain consequences of an action. Image You can embed a image in your page by using the following Markdown syntax: ![ <alt-text> ]( <image-link> ) Example: ![alt-text](https://learn.microsoft.com/en-us/media/learn/not-found/learn-not-found-light-mode.png?branch=main) This will be rendered as: 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. You can reuse a common text snippet within a sentence using inline include: Text before [!INCLUDE [<title>](<filepath>)] and after. Or reuse an entire Markdown file as a block, nested within a section of an article. Block include is on its own line: [!INCLUDE [<title>](<filepath>)] Where <title> is the name of the file and <filepath> is the relative path to the file. Included markdown files needs to be excluded from build, they are usually placed in the /includes folder. Code Snippet There are several ways to include code in an article. The code snippet syntax replaces code from another file: [!code-csharp[](Program.cs)] You can include selected lines from the code snippet using region or line range syntax: [!code-csharp[](Program.cs#region)] [!code-csharp[](Program.cs#L12-L16)] Code snippets are indicated by using a specific link syntax described as follows: [!code-<language>[](<filepath><query-options>)] Where <language> is the syntax highlighting language of the code and <filepath> is the relative path to the markdown file. Highlight Selected Lines Code Snippets typically include more code than necessary in order to provide context. It helps readability when you highlight the key lines that you're focusing on. To highlight key lines, use the highlight query options: [!code-csharp[](Program.cs?highlight=2,5-7,9-)] The example highlights lines 2, line 5 to 7 and lines 9 to the end of the file. using System; using Azure; using Azure.Storage; using Azure.Storage.Blobs; class Program { static void Main(string[] args) { // Define the connection string for the storage account string connectionString = \"DefaultEndpointsProtocol=https;AccountName=<your-account-name>;AccountKey=<your-account-key>;EndpointSuffix=core.windows.net\"; // Create a new BlobServiceClient using the connection string var blobServiceClient = new BlobServiceClient(connectionString); // Create a new container var container = blobServiceClient.CreateBlobContainer(\"mycontainer\"); // Upload a file to the container using (var fileStream = File.OpenRead(\"path/to/file.txt\")) { container.UploadBlob(\"file.txt\", fileStream); } // Download the file from the container var downloadedBlob = container.GetBlobClient(\"file.txt\").Download(); using (var fileStream = File.OpenWrite(\"path/to/downloaded-file.txt\")) { downloadedBlob.Value.Content.CopyTo(fileStream); } } } 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 $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. Here's an example of the tab experience: Linux Windows Content for Linux... Content for Windows... The above tab group was created with the following syntax: # [Linux](#tab/linux) Content for Linux... # [Windows](#tab/windows) Content for Windows... --- Tabs are indicated by using a specific link syntax within a Markdown header. The syntax can be described as follows: # [Tab Display Name](#tab/tab-id) A tab starts with a Markdown header, #, and is followed by a Markdown link [](). The text of the link will become the text of the tab header, displayed to the customer. In order for the header to be recognized as a tab, the link itself must start with #tab/ and be followed by an ID representing the content of the tab. The ID is used to sync all same-ID tabs across the page. Using the above example, when a user selects a tab with the link #tab/windows, all tabs with the link #tab/windows on the page will be selected. Dependent tabs It's possible to make the selection in one set of tabs dependent on the selection in another set of tabs. Here's an example of that in action: .NET .NET TypeScript TypeScript REST API .NET content for Linux... .NET content for Windows... TypeScript content for Linux... TypeScript content for Windows... REST API content, independent of platform... Notice how changing the Linux/Windows selection above changes the content in the .NET and TypeScript tabs. This is because the tab group defines two versions for each .NET and TypeScript, where the Windows/Linux selection above determines which version is shown for .NET/TypeScript. Here's the markup that shows how this is done: # [.NET](#tab/dotnet/linux) .NET content for Linux... # [.NET](#tab/dotnet/windows) .NET content for Windows... # [TypeScript](#tab/typescript/linux) TypeScript content for Linux... # [TypeScript](#tab/typescript/windows) TypeScript content for Windows... # [REST API](#tab/rest) REST API content, independent of platform... ---"
   },
   "index.html": {
     "href": "index.html",

diff --git a/...ticles-markdown.html-tabs-windows-2Ctypescript-markdown-extensions.verified.png b/...ticles-markdown.html-tabs-windows-2Ctypescript-markdown-extensions.verified.png
diff --git a/...ticles-markdown.html-tabs-windows-2Ctypescript-markdown-extensions.verified.png b/...ticles-markdown.html-tabs-windows-2Ctypescript-markdown-extensions.verified.png
diff --git a/...ticles-markdown.html-tabs-windows-2Ctypescript-markdown-extensions.verified.png b/...ticles-markdown.html-tabs-windows-2Ctypescript-markdown-extensions.verified.png