Known markdown parser crashers about aio-theme HOT 15 CLOSED

Hi @bdenham, thanks for the quick reply. I fixed this one myself. It turned out that I had used the old something syntax, which Gatsby for sure does not like. Changing it to something worked.

from aio-theme.

That's because the parser is based on JSX and JSX doesn't allow non closed tags.

from aio-theme.

Errors like '"gatsby-plugin-mdx" threw an error while running the onCreatePage lifecycle:' are probably helpful to Gatsby developers with the source code, but are not helpful to content writers trying to figure out why things are failing. Putting the offending .md file (or config file) into the error message would be super helpful.

from aio-theme.

Hey @chuckweger, I'm working on a solution to this issue now. As @icaraps said, when you have HTML tags that are not closed within your markdown files (such as, <br>, <hr>, <image>), the parser will not recognize these tags as proper JSX, which will throw the error. Where are the docs (what repo) you are parsing? I can take a look and let you know which tags and files are causing the problem.

@ashryanbeats, yes, along with my fix, I'll create documentation about which tags the fix closes so writers can get in the habit of not including open HTML tags in their markdown.

Actually, I'm making this fix in the parliament-client-template, which will be migrated here at some point.

from aio-theme.

Wow, I should have quoted parts of that reply (forgot this uses markdown). Let's try again.
I formerly used:

<b>something</b>

but am now using

**something**

from aio-theme.

Yeah, making sure everything in a markdown file is actually markdown is definitely a process. Takes time when working through legacy markdown to ensure that the loose HTML tags are either replaced by their markdown equivalents, closed, or removed.

BTW, thanks for clarifying that. I wasn't aware the <b>something</b> would break the mdx parser. Good to know.

from aio-theme.

Gatsby does not like local URLs with dashes.
For example:

throws this error:

TypeError: undefined is not an object (evaluating '_allSitePage$nodes$fi.componentPath')

Changing this to

[look here](../code_samples/

Makes everything fine again.

from aio-theme.

Sheesh. I will never get the hang of posting comments in markdown syntax. Sorry!

OLD code that throws the error:

[look here](../code-samples/)

NEW CODE THAT WORKS:

[look here](../code_samples/)

from aio-theme.

Great. Keep them coming. I'm creating a markdown file for testing that will have your examples as well as several tags I know to check for. So your input here is a good a place as any to note your problem markdown. Thanks!

from aio-theme.

<ContentBlock slots="text"/>
While this documentation...

The parser is parsing the above markdown as [ContentBlock, String].

If you add a linebreak before the text:

<ContentBlock slots="text"/>

While this documentation...

The parser is parsing it as [ContentBlock, Paragraph] which is what a ContentBlock is expecting.

from aio-theme.

Thanks, @icaraps. Yes, this applies for any JSX tag within an .mdx file or an .md file processed as MDX. That's what makes cleaning up an .md file that has <br> and <hr> tags so difficult. Because even if you close the invalid tags that break the build (using <br/>, <hr/>, etc), you still have to add line breaks to make the MDX parser render them as anything other than text strings.

For example, if you have a second-level heading immediately following a closed break tag in your markdown:

<br/>
## Heading level 2

The MDX parser will treat the heading (## Heading level 2) -- or anything else! -- as text that is a part of the closed <br/> tag:

"type": "jsx",
"value": "<br/>\n## Heading level 2",

So in this case, the HTML output renders without a tag, displaying it as simple text in the browser:

<br />
## Heading level 2

Instead of how it should be rendered as a level 2 heading:

<br />
<h2>Heading level 2</h2>

So, I'm working on a solution to ensure that both the invalid tags are fixed and the extra lines are added where needed.

from aio-theme.

I've got a draft PR for a new gatsby plugin in the parliament-client-template that fixes tags which cause know MDX/JSX parsing errors: adobe/parliament-client-template#36.

I can also create a node CLI for this as well, which could be run locally and committed to your docs repo on GitHub to fix the issues. Is there any interest in such a CLI?

from aio-theme.

@bdenham sure we have a CLI so maybe just add it there https://github.com/adobe/aio-cli-plugin-doc ? Maybe as part of adobe/aio-cli-plugin-doc#8 ?

from aio-theme.

@icaraps Cool. I'll check it out. Thanks.

from aio-theme.

AdobeDocs/dev-site-documentation-template#81 should help to prevent these issues

from aio-theme.