Markdown: Parsing fails when putting a Typescript type outside of the code block

[Tulean]

🐛 Bug Report

Hello I am having an issue with being unable to parse markdown generated by microsoft api-extractor. The problem is that I am having some interfaces outside of the code block for example Array which parses Array as text and as an html tag. Which results in an error requiring me to provide a closing tag as well even though it should be an Array with a string type.

What is happening is that docusaurus is parsing Array<string> as Array as a string and as an jsx tag.

Similar issue reported: #2708 ; however , it was closed with no clear asnwer.

Have you read the Contributing Guidelines on issues?

yes

To Reproduce

If possible, use https://new.docusaurus.io to create a CodeSandbox reproducible demo of the bug.

(Write your steps here:)

1. Use Microsoft api-extractor to generate api markdown.
2. Put the markdowns under a folder of docs.
3. yarn start

Expected behavior

Docusaurus is started successfully.

Actual Behavior

Your Environment

• Public source code:
• Public site url:
• Docusaurus version used: 2.0.0-alpha.72
• Environment name and version (e.g. Chrome 78.0.3904.108, Node.js 10.17.0):
• Operating system and version (desktop or mobile):

Reproducible Demo

If possible, use https://new.docusaurus.io to create a CodeSandbox reproducible demo of the bug.

(Paste the link to an example repo, including a docusaurus.config.js, and exact instructions to reproduce the issue.)

[slorber]

We use the MDX parser and your markdown must be compatible with it. It is not a bug and is the current intended behavior.

You can check if MDX can compile your markdown with https://mdxjs.com/playground/

• If your md compile in the playground, and does not compile in Docusaurus, it is a bug.
• If your md does not compile in the playground, we can't do anything currently.

MDX will not like Array<string>

But there are ways to escape these chars. For example, we use this in the Jest website: [array<string>] and it renders correctly: https://github.com/facebook/jest/blob/master/docs/Configuration.md#coveragepathignorepatterns-arraystring

The options you have:

1. Fix yourself the markdown emitted by api-extractor before giving it to Docusaurus so that it is compatible with MDX. You can use regexp and string.replace().
2. Use Docusaurus 1 or another tool that is compatible with the api-extractor output
3. Wait for Docusaurus 2 to support multiple markdown parsers: RFC: CommonMark compatibility, supporting multiple markdown/content parsers #3018

I suggest option1, and when we'll have an alternate parser (#3018) you could move to option 3. Just keep in mind that only MDX will allow you to make your doc more interactive by embedding React code in your docs.

[Tulean]

@slorber thanks for the thorough explanation. I was also suspecting that, I tried to replace the parser with some plugins but it seems that it does not work yet. I will keep an eye on it.

[adventure-yunfei]

+1 for this.

I'm also a user of api-extractor (to genenrate a nice api-docs site), and trying to migrate doc site generator to docusaurus.

After some investigation, it's really hard to adopt option 1. Besides un-closed tags, there're still some other cases that mdx cannot compile. e.g.

<b>Signature:</b> { foo: string; }

I chose option 2 - using docusaurus v1. But looking forward to option 3. It's perfect to support original markdown parser for part of the docs!