[Docs] Move Reference Compilation Issues with MDX

[hariria]

Aptos Documentation Issue (Internal)

Unfortunately, it seems as though Move doc-gen does not compile MDX compatible markdown documents, which makes it challenging to create a Move Reference page.

Repro

Example: https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/move-stdlib/doc/acl.md

If you copy, paste into the playground below, you will receive an error 102:41: Could not parse expression with acorn

Test here: https://mdxjs.com/playground/

Root Cause

It seems as though mdx is unable to compile the code snippets within the markdown. It's trying to process { braces as inline code / JSX components I believe.

Desired Solution

Ideally, the generated docs could use HTML Entities, which will properly render the curly braces { and } with } and } instead and <, > with < and >. Same with other characters.

Example

Before HTML Entities

<pre><code><b>public</b> <b>fun</b> <a href="acl.md#0x1_acl_empty">empty</a>(): <a href="acl.md#0x1_acl_ACL">ACL</a> {<a href="acl.md#0x1_acl_ACL">ACL</a>{ list: <a href="vector.md#0x1_vector_empty">vector::empty</a>&lt;<b>address</b>&gt;() }}</code></pre>

After HTML Entities

<pre><code><b>public</b> <b>fun</b> <a href="acl.md#0x1_acl_empty">empty</a>(): <a href="acl.md#0x1_acl_ACL">ACL</a> &#123;<a href="acl.md#0x1_acl_ACL">ACL</a>&#123; list: <a href="vector.md#0x1_vector_empty">vector::empty</a>&lt;<b>address</b>&gt;() &#125;&#125;</code></pre>

Requirements for MDX Doc-Gen

1. Compiles to MDX compatible markdown. To test MDX compatibility, you can use https://mdxjs.com/playground/
2. Ensure that the MDX code preserves the original Markdown's structure and rendering. The content should appear the same way it would if written in standard Markdown
   • As an example both code snippets below are correct markdown, but the second code snippet is the correct formatting since we want the header to be separate from the content

     { /** snippet 1 */} 
     # Module `0x1::acl`  Access control list (acl) module.

     { /** snippet 2 */} 
     # Module `0x1::acl`  
     Access control list (acl) module.

[brmataptos]

Can you give a complete list of characters that are not liked? I'm used to using < and > but needing to escape { and } is new. What else?

[brmataptos]

i.e., what did you mean by "Same with other characters."? Which characters?

[hariria]

@brmataptos chatgpt ftw

In MDX, there are several characters that can cause issues when not properly escaped. Here are the key characters to watch out for and their HTML entity equivalents:

Curly Braces {}

• { becomes {
• } becomes }

Angle Brackets <>

• < becomes <
• > becomes >

Ampersand &

• & becomes &

Quotes " and ' (less common issue in code snippets but still good to know)

• " becomes "
• ' becomes '

Backticks `

For backticks used in code blocks, you generally do not need to escape them within MDX. However, if backticks appear outside code blocks, you might need to ensure they are properly handled, often by enclosing them in backticks within the markdown itself.

Less common but sometimes relevant:

• # becomes #
• * becomes *
• + becomes +
• - becomes -
• = becomes =
• | becomes |
• ~ becomes ~

[github-actions[bot]]

This issue is stale because it has been open 45 days with no activity. Remove the stale label or comment - otherwise this will be closed in 15 days.