Support configuration for Markdig built-in extensions

[usigrist]

DocFX Version Used: 2.39.1

Is there a way to use grid tables by enabling the markdig Grid Table extension when using the markdig engine?

[herohua]

@yishengjin1413 @wh-alice

[usigrist]

Could this be done using the Property markdownEngineProperties in docfx.json with a new key and a list of native markdig extensions to be added during pipeline initialization? If yes I could implement it and provide a pull request.

[superyyrrzz]

It sounds good to me. @Thraka also want this extension (https://github.com/dotnet/docfx/issues/4201#issuecomment-474636674) and may like this idea.

@yishengjin1413 @wh-alice What do you think of this? I know docfx has some custom Markdig extension. My only concern is whether it will cause some conflict if we allow users to choose extensions.

[yishengjin1413]

@usigrist Sounds good. And I suggest you to add one method like builder.UseCustomExtensions(_context, config) in L143 before builder.UseDocfxExtensions(_context) . Since some extensions are added by order in DocfxExtensions.

[superyyrrzz]

Markdig also supports footnotes for #1564

[Thraka]

I would love this.

[sommmen]

Any update on footnote support?

[smokedlinq]

Hey @docs-product or someone else, will be this something we can look forward to in v3?

[cillroy]

we are evaluating this and looking into the impact on our design team

[tibel]

Enabling markdig Diagrams would be great too.

[lionelberton]

Enabling markdig Math formulas would be great too

[simonziegler]

I'm also keen to see footnotes, diagrams and maths formulae at some time.

[wangkanai]

Any progress regarding this issue? Its would make DocFX features extendibility top out everything.

[Himura2la]

I was surprised when I found out that it's not possible at the moment. Although there are some concerns on compatibility. In particular: Where how should the footnote descriptions be placed if they are in API or in an included file?

[mgregr]

Any update on this please?

[tobybaratta]

+1 on asking for an update. Footnotes are rather essential.

[jo3w4rd]

Currently, DocFX sets the "strikethrough" option for the Markdig "emphasisextra" extension, which overrides the use of other emphasis types.

https://github.com/dotnet/docfx/blob/d51b62378ab55fdf56244c3d5134f7c388fe5083/src/Microsoft.DocAsCode.MarkdigEngine.Extensions/MarkdownExtensions.cs#L21

Perhaps if the "user" specifies Markdig custom extensions in markdownEngineProperties, they should be responsible for setting all of them?

Also, is there a way to specify options for the Markdig extensions that are enabled?

And, can custom Markdig extensions be used directly? Or does that require recompiling DocFX locally?

[jakraft]

Perhaps if the "user" specifies Markdig custom extensions in markdownEngineProperties, they should be responsible for setting all of them?

That was something I asked about with the docfx devs when I was working on the PR, but they didn't think there was much of a need for disabling/modifying extensions that were already being used by DFM. That may require a separate change.

Also, is there a way to specify options for the Markdig extensions that are enabled?

Specifying options is not currently possible with this implementation, since it relies on MarkdownPipelineBuilder.Configure() method defined here.

And, can custom Markdig extensions be used directly? Or does that require recompiling DocFX locally?

By custom extensions, do you mean 3rd party extensions? That's not currently possible due to the same limitation as above. You'd need to update the switch statement in the Configure method.

[rclabo]

Wow, I can't believe this still isn't implemented. (sigh) It would be so nice to have a way to specify markdig extension to load.

[jakraft]

@rclabo this functionality was added with this change: #7833

To use, simply add the following to the build section of your docfx.json:

{
  "build": {
    "markdownEngineName": "markdig",
    "markdownEngineProperties": {
      "markdigExtensions": [
        "abbreviations",
        "definitionlists",
        "tasklists",
        "footnotes",
        ...
      ]
    }
  }
}

Note that the exact list of supported extensions can be found here. Some limitations to keep in mind:

1. Not all markdig extensions are supported using this feature at the moment. Only the ones linked above.
2. Customization of these extensions is not currently supported. They will load with their default configuration.
3. The docfx default theme may not support these extensions out of the box. The diagrams extension, for example, requires additional javascript to use. There may also be some minor CSS tweaks required to get stuff to render properly.
4. The default set of extensions used by DocFX cannot be disabled.

[cjlotz]

Just a question about emoji support. I see from the list of supported extensions that emojis are supported. I've setup my docfx.json:

"markdownEngineName": "markdig",
"markdownEngineProperties": {
  "markdigExtensions": [
    "emojis",
    "definitionlists",
    "tasklists",
    "footnotes"
  ],

and have some markdown with some emojis in docs/versioning.md file

Testing :angry: !!

I get the following exception

[22-06-09 06:30:38.296]Error:[BuildCore.Build Document.CompilePhaseHandlerWithIncremental.ConceptualDocumentProcessor.Build.BuildConceptualDocument](docs/versioning.md)Markup failed: Could not load file or assembly 'System.Runtime.CompilerServices.Unsafe, Version=4.0.4.1, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a' or one of its dependencies. The located assembly's manifest definition does not match the assembly reference. (Exception from HRESULT: 0x80131040).

The other extensions included work fine. Am I missing something obvious?