Docs-website: Migration scripts don't handle fenced code blocks within MDX well

[austin-schaefer]

Description

The NRQL syntax doc has some complicated syntax within collapsers, and the migration script is getting confused and pulling in all the content as code.

Steps to reproduce

1. Go to https://docs-preview.newrelic.com/docs/query-your-data/nrql-new-relic-query-language/get-started/nrql-syntax-clauses-functions
2. Compare with https://docs.newrelic.com/docs/query-your-data/nrql-new-relic-query-language/get-started/nrql-syntax-clauses-functions

Expected behavior

New doc should reproduce formatting/hierarchy of old doc.

Considerations

• This functionality is now available in MDX https://github.com/mdx-js/mdx/pull/1367

Useful links

• MDXv2 Umbrella Issue

[jerelmiller]

Investigating that page, it seems the MDX itself is just fine, but is being parsed incorrectly by the MDX parser (we are currently on an alpha version of v2). This tells me that at least our migration script is doing its job correctly. Depending on where things end up in the next couple months, we may need to manually patch this ourselves. Hopefully the MDX v2 parser is officially released soon with these outstanding bugs fixed.

[austin-schaefer]

Another doc where the parser is choking. Look at the metricName section in this doc: https://docs-preview.newrelic.com/docs/agents/java-agent/api-guides/java-agent-api-instrument-using-annotation

The "important" callout is being brought into the code block erroneously.

The dispatcher section suffers from a similar issue.

[jpvajda]

I'm thinking we may want to look at this in MMF8, what do you think @jerelmiller ?

[jerelmiller]

This one is tricky and unfortunately I think adding this to MMF 8 would blow that MMF up a bit. I would advocate for doing this a bit later.

The issue here isn't so much a problem with the migration script or the MDX itself. Looking at the MDX files for these pages, the syntax looks perfect. The issue stems from the fact that we are using an alpha version of MDX v2, which is still a work in progress. It works pretty well, but still has some bugs.

To be clear, the MDX library is what is responsible for taking MDX code and turning it into the JSX/HTML that you see on the page. Here I see that the code block in question is indented 4 spaces. This indicates to me that the MDX parser is having trouble figuring out where the code block ends, which is why you see the issue showing up on the docs site. In order to fix this, we'd need to patch MDX, or write an MDX plugin that tries to address this parsing issue. I could see that taking a significant amount of time depending on what the issue is under the hood (if we have to mess with the parser, that is pretty difficult).

I've been keeping watch on MDX v2 and hoping that we see some resolution on some of these issues soon. I'd advocate for holding out just a bit longer to see if there is a bug fix in the alpha version that addresses this.

You can see the issue I opened about this here: https://github.com/mdx-js/mdx/issues/1283

[jpvajda]

@jerelmiller ah yeah, I remember us discussing this now with the MDX V2.

[jpvajda]

Update the issue with stuff we discussed.

[tariqahmed]

Isn't this the same issue as

https://github.com/newrelic/docs-website/issues/116

?

[jerelmiller]

@tariqahmed not quite. This one has to do with the rendering of a fenced code block when used inside of a JSX element. In this case, either the parser or formatter is a bit off and instead of rendering a block of code, it envelops a bunch of the surrounding markup as well. You can see the issue at play here: https://github.com/mdx-js/mdx/issues/1283

116 is asking for the code blocks to support rendering var, mark and a tags inside of them. This isn't as much a rendering issue (bug) as it is a feature request.

[jpvajda]

This functionality is now available in MDX : https://github.com/mdx-js/mdx/pull/1367

[jerelmiller]

As soon as they push out a new version, we can go ahead and update.

[tariqahmed]

Effort basically involves:

• AST names changed, look at those and adjust migration script
• Upgrading MDX