[rich-text-from-markdown] all nodes returned to richTextFromMarkdown fallback are not created equal

[wgins]

Issue/Background We're in the midst of migrating a long-text field to rich-text. Our long text fields currently contain a mix of markdown/html including some <img></img> and <amp-img></amp-img> tags.

Initially we set out to use the rich-text-from-markdown package to convert all of these unhandled nodes using a custom fallback (following this guide) but struggled (for far too long) to figure out why a html type node was being treated differently from an unhandled image node type.

Eventually we realized richTextFromMarkdown passes slightly different nodes back to provided the fallback fn. image node types are hoisted https://github.com/contentful/rich-text/blob/f83fee241530faede47c98dbacb0ebcc762d13b1/packages/rich-text-from-markdown/src/index.ts#L212 whereas all other node types are not and therefore if you try to return an embedded-entry-block node from the fallback function it's nested within a paragraph node and Contentful rejects the entry.

Proposed Solution In our opinion richTextFromMarkdown method should make clear that not all unhandled nodes are treated equally and the documentation should be updated to reflect this. Similarly, it would be great to provide functionality to the end-user so that they can determine which node types should be hoisted or not.

Temporary Solution Eventually we forked the package and modified https://github.com/contentful/rich-text/blob/f83fee241530faede47c98dbacb0ebcc762d13b1/packages/rich-text-from-markdown/src/index.ts#L212 to read if (node.children[i].type === 'image' || node.childen[i].type === 'html') { which solved our problem.

Lastly, it would be nice if this package exposed the config of the processor on https://github.com/contentful/rich-text/blob/f83fee241530faede47c98dbacb0ebcc762d13b1/packages/rich-text-from-markdown/src/index.ts#L290. In our case we had markdown in our long-text field that looked like ##Some header and to handle this we needed to modify https://github.com/contentful/rich-text/blob/f83fee241530faede47c98dbacb0ebcc762d13b1/packages/rich-text-from-markdown/src/index.ts#L290 to const processor = unified().use(markdown, { commonmark: true, pedantic: true }); to loosen the strictness settings.

Hope this helps anyone else going through a similar process!