Is it possible to escape HTML so I can use MDX in descriptions?

[Preston-Landers]

I want to reuse a common component (MDX) in several areas of my OpenAPI spec as shown in the example below.

The <b> tags are getting passed through, but the < in <UnderConstruction /> is getting transformed to < UnderConstruction />, which of course makes the component not render as desired. And <blink> doesn't work, sadly. So it seems like maybe there's a whitelist of allowed tags.

Is there an escape hatch if I want to get crazy and put MDX components in my OpenAPI description fields?

api-keys-delete:
  post:
    summary: Delete API Keys
    description: |
      Delete one or more API keys by their internal ID.

      <blink>Hello</blink>, <b>world</b>!

      import UnderConstruction from '../partials/\_under-construction.mdx'

      <UnderConstruction />

Gets translated to this MDX:

<MethodEndpoint
  method={"post"}
  path={"/api_keys/delete_api_keys"}
  context={"endpoint"}
>
</MethodEndpoint>


Delete one or more API keys by their internal ID.

<blink&gt;Hello</blink&gt;, <b>world</b>!

import UnderConstruction from '../partials/\_under-construction.mdx'

&lt;UnderConstruction />

[sserrata]

Hi @Preston-Landers, thanks for reporting this issue...we do in fact whitelist tags/elements using a regex pattern, mainly to url encode special chars that could otherwise be confused with JSX and cause compilation errors. That said, I am wondering if this strategy makes much sense because it does force us to limit MDX support, including all the built-in Docusaurus MDX components and even custom components. My first inclination is to revisit whether the escapes are even necessary, or if we should rather lean more on users to handle escaping or MDX formatting on their own. Interested to hear your thoughts.

And yes, it really is a shame the <blink> tag was nerfed 😆

[Preston-Landers]

Thanks for the reply. I think it probably does make sense to escape tags by default. I was wondering if there was a way to escape / bypass that, in case I know what I'm doing (spoiler: I don't).

At least for my use cases, there's a certain amount of repeated content fragments that show up in my OpenAPI description fields and I was hoping to DRY them by putting them in a nice MDX component. That was my goal, anyway. I am not familiar with the source of this project but next week I can look into whether a pull request is feasible, but it would be good if a more knowledgeable developer could weigh in on the advisability of this.

[Preston-Landers]

So I was thinking about this a bit more. I forked the repo and found the clean() function in src/markdown/utils.ts. I cobbled together a version of it that looks for {% no_escape %} at the beginning of the string, and if found, removes that marker and disables the escaping of greater than / less than. I can post that later.

While that does seem to work, it doesn't get me all the way to my ultimate goal. The problem is the import statement. I'm not super familiar with this stuff, but it appears that the import statement must not be indented within MDX files otherwise it won't be executed as an import. But in these MDX blocks being emitted for the OpenAPI items, the block containing the import will be indented, so the compiler fails with unknown component.

I think there might be a few potential solutions to that but I haven't fully explored them. Perhaps something to do with the markdownGenerators feature? Maybe I can use that to make my desired components be imported automatically. I assume there's no other existing functionality for a "global component import"? Any thoughts are welcome. Thanks!

[Preston-Landers]

OK so I found what I think will be a cleaner solution, at least for me, which is simply a post-processing step in between the output of this plugin and the Docusaurus compilation step. I wrote a script that looks for blocks like this:

responses:
      "204":
        description: |
          The user was successfully deleted. The response body is empty.

          # START_RAW

          import UnderConstruction from '../../partials/\_under-construction.mdx'

          <UnderConstruction />

          # END_RAW

In my script I remove the block markers, dedent the whole block, and un-escape the < and > chars.

That seems to do the trick, at lest for my goals. I can post my script here later. Or maybe the discussion forums would be a better place.

[ImFlog]

Just pinging to say that I have the exact same issue. In previous version the clean did not exist and we used this extensively to render custom component or import other pages from the OpenAPI description.

Would it be possible to add a parameter to disable the description cleaning for instance ?
I can give it a shot if you think this is good idea.

[Preston-Landers]

For what it's worth, here's that script I mentioned. This can be run as a post-processing step in between docusaurus-openapi-docs and the main docusaurus build, to un-escape "RAW" blocks. This lets you include custom components in an OpenAPI spec and have it rendered out in the site.

https://gist.github.com/Preston-Landers/6f65b0b0e264eb02e71e5c7dee3813f8

[ImFlog]

Thank you but, for my use case I only needed to escape <.
Thus I added a sed command in a Makefile that generate the pages, but it's far from ideal 😅

[sserrata]

This is sort of related to #1012 except it's the inverse problem. We introduced escaping to avoid MDX parsing issues, but now that we're CSR it may no longer be necessary. Still, we'll need to test whether inline HTML/JSX like this will work.

[sserrata]

Hi @Preston-Landers, now that #1016 is merged, was hoping you could help test the latest canary release to see if your issue is resolved. Thanks!

[Preston-Landers]

Hi @sserrata - I just mentioned in #1012 that canary version 0.0.0-956 fixed that issue where admonitions were not working in API description fields.

The issue described here in #993 is a bit different in that I was trying to use custom MDX components, rather than built-in Docusaurus markup like admonitions. Unfortunately, that is still not working - with the latest canary, the custom HTML tags still get escaped like shown in the first comment here in this issue.

Fortunately, the workaround I posted hetre of a custom post-processing script does still work. That script looks for marked blocks and undoes the escaping.

The demo repository I set up for #1012 now illustrates this script if you want to take a look:
https://github.com/Preston-Landers/docusaurus-openapi-upgrade-bug-demo/tree/check-issue-993

The yarn build step runs script/fix-openapi-mdx-blocks.mjs which finds the START_RAW / END_RAW blocks and unescapes them. While this probably isn't the cleanest solution in the world, it's working well enough for me. Having some kind of native support would be very nice, though.