Strip markdown from parameter placeholder

[pmarschik]

Describe the bug

Have a parameter defined for some path. That parameter can have a description which according to the OAS spec supports CommonMark syntax.

This description is used by packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/ParamOptions/ParamFormItems/ParamTextFormItem.tsx (and ParamArrayFormItem.tsx) as placeholder on the <FormTextInput>.

This would show raw markdown if description contains markdown (e.g. a raw markdown link such as leading [Some link](/pointing/somewhere) trailing.

Expected behavior

Strip the markdown to plaintext so the placeholder text is readable. The correctly rendered markdown is anyways in the main section.

So leading [Some link](/pointing/somewhere) trailing should become leading Some link trailing.

Current behavior

Raw markdown is rendered as text.

Possible solution

Maybe use something like https://github.com/remarkjs/strip-markdown to strip non markdown elements.

Your Environment

• Version used: 4.1.0

[sserrata]

Hi @pmarschik, this is likely related to #1012. Basically, we need to decide whether we want to re-introduce remark rendering of descriptions/summaries or if Docusaurus could possibly provide a hook or method for rendering Docusaurus-style MDX client-side.

[pmarschik]

Yes, except for the detail that #1012 is about 4.2 and I tested this with 4.1.

I'd love for docusaurus to expose their MDX parsing facility client-side so the same markdown could be used. I know that the OAS spec just specifies CommonMark but having the same abilities as Docusaurus would be awesome.

I've just had a cursory look at the docusaurus code and all of their parsing seems to be in the @docusaurus/mdx-loader package. However, not enough is exposed to clients to be able to use that. Maybe @slorber has plans to expose more of the functionality there? (or a JSX component where one could pass raw MDX that gets rendered by Docusaurus).

[slorber]

I'm not sure to understand the problem, but overall we don't really plan to ship an MDX parser/renderer to the client side 😅 This would increase the weight of the client-side application. We don't prevent you from doing it yourself though (MDX can run in a browser), but beware of the tradeoffs you make.

[pmarschik]

So whats happening in this plugin:

• there is an OpenApi specification (OAS) document
• some items of that document contain raw markdown text.
• the plugin has a few React components that render these items
• right now the raw markdown from the OAS document is rendered directly with react-markdown like <ReactMarkdown children={rawMarkdown} />

But it would be awesome to get access to the configured MDX processor to render that raw markdown text. That way all configured remark/rehype plugins would work, as well as being able to use all configured mdx components.

[sserrata]

Thanks @pmarschik, I think that's the basic approach/idea - that the plugin could somehow use the custom remark plugins located here: https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-mdx-loader/src/remark

[slorber]

Unfortunately, it's unlikely to happen.

Those remark plugins have various dependencies, some of them don't even work in a browser. Some plugins even use fs.readFile. User-provided plugins might also depend on Node.js env.

At best, we can expose a subset of the plugins, but it's impossible to expose all of them and expect things to work in a browser.

The questions are:

• Which plugins do you need exactly?
• What's the exhaustive list of behaviors that you want to port?
• Why does this plugin do this at runtime instead of build time?

Shipping react-markdown to the browser is expensive. Maybe it could pre-parse the md on the Node.js side and pass the AST to the browser. That makes the system more lightweight and still gives the flexibility for a theme to provide custom components to render Markdown elements.