Optionally enable Markdig extensions that are not included by default in DocFX

[jakraft]

Taking a first crack at #3387

This change will allow users to optionally enable various Markdig extensions that are disabled by default in DocFX. The following extensions are included in this change (more can be added later):

• Task lists
• Grid tables
• Footnotes
• Mathematics
• Diagrams
• Definition lists

To enable them, simply include them as a property in your markdownEngineProperties (make sure Markdig is set as your markdownEngine):

{
  "build": {
    ...
    "markdownEngineName": "markdig",
    "markdownEngineProperties": {
      "enableTaskLists": true,
      "enableDefinitionLists": true
    }
  }
}

[dnfadmin]

All CLA requirements met.

[yufeih]

Thank you for the enhancement!

The tests and parameter passing flow looks good, I wonder if it is possible to use the configuration vocabularies provided by markdig, this way we don't have to invent our own configuration options and would pickup latest markdig extensions without code change, something like:

{
  "build": {
    "markdownEngineName": "markdig",
    "markdownEngineProperties": {
      "markdigExtensions": [
          "common",
          "pipetables"
      ]
    }
  }
}

We'll also need a special extension name to represent the current docfx setup as the default like "dfm" (Docfx Favored Markdown).

[jakraft]

@yufeih Ah that's a much better solution! I wish I had spotted that earlier. Could you please clarify what you mean by this:

We'll also need a special extension name to represent the current docfx setup as the default like "dfm" (Docfx Favored Markdown).

Is the expectation here that users should always include "dfm" in the list of extensions, and if it's not included then we shouldn't call UseDocFxExtensions()? I would have figured we'd want those extensions to always be applied.

Somewhat outside the scope of this change, it may also be worth considering adding a "disabledMarkdigExtensions" property to allow users to opt-out of certain extensions. That would allow new extensions to be enabled by default in the future while maintaining backward compatibility with existing documentation. I don't think it's strictly necessary for this first iteration though.

[jakraft]

Updated the implementation to use a list of extensions as per @yufeih's suggestion. It may make sense to add a "disabledMarkdigExtensions" later, but that might be tricky to do. The best way I could think to do that is to make a separate MarkdownPipelineBuilder instance, calling Configure() on the list of disabled extensions, and then calling builder.Extensions.RemoveAll(e => disabledExtensionsBuilder.Extensions.Contains(de => de.GetType() == e.GetType()). Not a very elegant solution.

[yufeih]

@jakraft

How about markdownExtensions defaults to ["dfm"] when absent and we treat all extensions equally, this could addresses the extension removal problem:

• {}: fallback to ["dfm"] with all docfx extensions applied
• { markdownExtensions: [] } : No markdown extensions at all
• { markdownExtensions: ['dfm', 'tasklists'] }: Docfx extensions and tasklists
• { markdownExtensions: ['tasklists'] }: Tasklists only

[yufeih]

There doesn't seem to be a strong desire to remove a markdown extension, most of the time you can just avoid using the syntax. So the design implemented in this PR looks good.