[api-documenter] Implement separate output target for Docusaurus MDX

[octogonz]

Summary

Docusaurus uses the .md file extension, but its syntax is MDX not Markdown. A number of Markdown constructs don't get rendered correctly by MDX.

Test cases

Here's a punch list of test cases that we should validate after implementing an dedicated MDX emitter:

• In https://github.com/microsoft/rushstack/commit/42318bc7e7a4984d49ee8d996495656cb3281282 the <categoryFolder> parts get emitted as TSDoc HTML elements which break Docusuarus:

    /**
     * The minimum allowable folder depth for the projectFolder field in the rush.json file.
     * This setting provides a way for repository maintainers to discourage nesting of project folders
     * that makes the directory tree more difficult to navigate.  The default value is 2,
     * which implements a standard 2-level hierarchy of <categoryFolder>/<projectFolder>/package.json.
     */
  

• The <b> element disables link parsing for the rest of the line:

  <b>Extends:</b> [CommandLineParameterProvider](./ts-command-line.commandlineparameterprovider.md)
  

  The fix was to use *Extends:* instead of <b>. MDX 2 resolves this issue, but Docusaurus is currently stuck on MDX 1.

• @elliot-nelson encountered some trouble with handling of <!-- --> sequences:

  api-documenter-docusaurus-plugin/src/DocusaurusMarkdownFeature.ts

   // Requires more investigation. HTML comments are ok, but the little empty
   // comments (<!-- -->) that are inserted in between links break the MDX parser
   // in Docusuarus.
   eventArgs.pageContent = eventArgs.pageContent.replace(/<!-- -->/g, ' ');
  

  Maybe it is another case where any JSX-looking syntax disables parsing of Markdown syntaxes for that line. (?)

• @nazarhussain reported an issue in the #api-extractor channel that turned out to be different parsing when { } are present:

  <b>Important:</b> These values should be preferred. {alpha: true}