Optionally enable Markdig extensions that are not included by default…

… in DocFX (#7833)
dotnet · Jan 17, 2022 · 48dc846 · 48dc846
1 parent 6d5d0dd
commit 48dc846
Show file tree

Hide file tree

Showing 5 changed files with 98 additions and 5 deletions.
diff --git a/src/Microsoft.DocAsCode.MarkdigEngine.Extensions/Constants.cs b/src/Microsoft.DocAsCode.MarkdigEngine.Extensions/Constants.cs
@@ -11,5 +11,23 @@ public static class WarningCodes
         {
             public const string InvalidTabGroup = "InvalidTabGroup";
         }
+
+        /// <summary>
+        /// Names of properties supported in the markdownEngineProperties
+        /// property in the docfx.json
+        /// </summary>
+        public static class EngineProperties
+        {
+            /// <summary>
+            /// Enables the <see cref="LineNumberExtension"/>.
+            /// </summary>
+            public const string EnableSourceInfo = "EnableSourceInfo";
+
+            /// <summary>
+            /// Contains a list of optional Markdig extensions that are not
+            /// enabled by default by DocFX.
+            /// </summary>
+            public const string MarkdigExtensions = "markdigExtensions";
+        }
     }
 }
diff --git a/src/Microsoft.DocAsCode.MarkdigEngine.Extensions/MarkdownExtensions.cs b/src/Microsoft.DocAsCode.MarkdigEngine.Extensions/MarkdownExtensions.cs
@@ -4,6 +4,8 @@
 namespace Microsoft.DocAsCode.MarkdigEngine.Extensions
 {
     using System;
+    using System.Collections.Generic;
+    using System.Linq;
     using Markdig;
     using Markdig.Extensions.AutoIdentifiers;
     using Markdig.Extensions.CustomContainers;
@@ -39,6 +41,26 @@ public static MarkdownPipelineBuilder UseDocfxExtensions(this MarkdownPipelineBu
                 .RemoveUnusedExtensions();
         }
 
+        /// <summary>
+        /// Enables optional Markdig extensions that are not added by default with DocFX
+        /// </summary>
+        /// <param name="pipeline">The markdown pipeline builder</param>
+        /// <param name="optionalExtensions">The list of optional extensions</param>
+        /// <returns>The pipeline with optional extensions enabled</returns>
+        public static MarkdownPipelineBuilder UseOptionalExtensions(
+            this MarkdownPipelineBuilder pipeline,
+            IEnumerable<string> optionalExtensions)
+        {
+            if (!optionalExtensions.Any())
+            {
+                return pipeline;
+            }
+
+            pipeline.Configure(string.Join("+", optionalExtensions));
+
+            return pipeline;
+        }
+
         private static MarkdownPipelineBuilder RemoveUnusedExtensions(this MarkdownPipelineBuilder pipeline)
         {
             pipeline.Extensions.RemoveAll(extension => extension is CustomContainerExtension);

diff --git a/src/Microsoft.DocAsCode.MarkdigEngine/MarkdigMarkdownService.cs b/src/Microsoft.DocAsCode.MarkdigEngine/MarkdigMarkdownService.cs
@@ -15,6 +15,7 @@ namespace Microsoft.DocAsCode.MarkdigEngine
     using Markdig.Syntax;
     using Microsoft.DocAsCode.Plugins;
     using Microsoft.DocAsCode.Common;
+    using System.Collections.Generic;
 
     public class MarkdigMarkdownService : IMarkdownService
     {
@@ -136,7 +137,7 @@ public MarkupResult Render(MarkdownDocument document, bool isInline)
         private MarkdownPipeline CreateMarkdownPipeline(bool isInline, bool enableValidation)
         {
             object enableSourceInfoObj = null;
-            _parameters?.Extensions?.TryGetValue("EnableSourceInfo", out enableSourceInfoObj);
+            _parameters?.Extensions?.TryGetValue(Constants.EngineProperties.EnableSourceInfo, out enableSourceInfoObj);
 
             var enableSourceInfo = !(enableSourceInfoObj is bool enabled) || enabled;
 
@@ -160,6 +161,13 @@ private MarkdownPipeline CreateMarkdownPipeline(bool isInline, bool enableValida
                 builder.UseInlineOnly();
             }
 
+            object optionalExtensionsObj = null;
+            if ((_parameters?.Extensions?.TryGetValue(Constants.EngineProperties.MarkdigExtensions, out optionalExtensionsObj) ?? false)
+                && optionalExtensionsObj is IEnumerable<object> optionalExtensions)
+            {
+                builder.UseOptionalExtensions(optionalExtensions.Select(e => e as string).Where(e => e != null));
+            }
+
             return builder.Build();
         }
 

diff --git a/test/Microsoft.DocAsCode.MarkdigEngine.Extensions.Tests/GeneralTest.cs b/test/Microsoft.DocAsCode.MarkdigEngine.Extensions.Tests/GeneralTest.cs
@@ -23,9 +23,9 @@ public void MarkdigWithDefaultFAL()
 
         [Fact]
         [Trait("Related", "DfmMarkdown")]
-        public void TestDfm_TaskList()
+        public void TestDfm_TaskList_ExtensionDisabledByDefault()
         {
-            // Confirm that the [ ] and { } in the middle of list should not be parsed.
+            // Confirm that the [ ] and { } in the middle of list should not be parsed by default.
             var source = @"* Not contain a special character: &#92; ! # $ % & * + / = ? ^ &#96; { } | ~ < > ( ) ' ; : , [ ] "" @ _";
             var expected = @"<ul>
 <li>Not contain a special character: \ ! # $ % &amp; * + / = ? ^ ` { } | ~ &lt; &gt; ( ) ' ; : , [ ] &quot; @ _</li>
@@ -34,6 +34,48 @@ public void TestDfm_TaskList()
             TestUtility.VerifyMarkup(source, expected);
         }
 
+        [Fact]
+        [Trait("Related", "DfmMarkdown")]
+        public void TestDfm_TaskList_ExtensionEnabled()
+        {
+            // Confirm that the [ ] and { } in the middle of list should be parsed if the Task List extension is enabled.
+            var source = @"* Not contain a special character: &#92; ! # $ % & * + / = ? ^ &#96; { } | ~ < > ( ) ' ; : , [ ] "" @ _";
+            var expected = @"<ul class=""contains-task-list"">
+<li class=""task-list-item"">Not contain a special character: \ ! # $ % &amp; * + / = ? ^ ` { } | ~ &lt; &gt; ( ) ' ; : , <input disabled=""disabled"" type=""checkbox"" /> &quot; @ _</li>
+</ul>
+";
+            TestUtility.VerifyMarkup(source, expected, optionalExtensions: new List<string>
+            {
+                "tasklists"
+            });
+        }
+
+        [Fact]
+        [Trait("Related", "DfmMarkdown")]
+        public void TestDfm_MultipleOptionalExtensionsEnabled()
+        {
+            // Confirm that multiple optional extensions can be enabled at once
+            var source = @"* Not contain a special character: &#92; ! # $ % & * + / = ? ^ &#96; { } | ~ < > ( ) ' ; : , [ ] "" @ _
+
+Term 1
+:   Definition 1";
+            var expected = @"<ul class=""contains-task-list"">
+<li class=""task-list-item"">Not contain a special character: \ ! # $ % &amp; * + / = ? ^ ` { } | ~ &lt; &gt; ( ) ' ; : , <input disabled=""disabled"" type=""checkbox"" /> &quot; @ _</li>
+</ul>
+
+<dl>
+<dt>Term 1</dt>
+<dd>Definition 1</dd>
+</dl>
+";
+
+            TestUtility.VerifyMarkup(source, expected, optionalExtensions: new List<string>
+            {
+                "tasklists",
+                "definitionlists"
+            });
+        }
+
         [Fact]
         [Trait("Related", "DfmMarkdown")]
         public void TestDfm_HeadingId()

diff --git a/test/Microsoft.DocAsCode.MarkdigEngine.Extensions.Tests/TestUtility.cs b/test/Microsoft.DocAsCode.MarkdigEngine.Extensions.Tests/TestUtility.cs
@@ -23,11 +23,13 @@ public static void VerifyMarkup(
             string filePath = "test.md",
             Dictionary<string, string> tokens = null,
             Dictionary<string, string> files = null,
-            Action<MarkdownObject> verifyAST = null)
+            Action<MarkdownObject> verifyAST = null,
+            IEnumerable<string> optionalExtensions = null)
         {
             errors = errors ?? Array.Empty<string>();
             tokens = tokens ?? new Dictionary<string, string>();
             files = files ?? new Dictionary<string, string>();
+            optionalExtensions = optionalExtensions ?? new List<string>();
 
             var actualErrors = new List<string>();
             var actualDependencies = new HashSet<string>();
@@ -42,7 +44,8 @@ public static void VerifyMarkup(
 
             var pipelineBuilder = new MarkdownPipelineBuilder()
                 .UseDocfxExtensions(markdownContext)
-                .UseYamlFrontMatter();
+                .UseYamlFrontMatter()
+                .UseOptionalExtensions(optionalExtensions);
 
             if (lineNumber)
             {