jsdoc-to-markdown generates invalid Markdown

[Anthony-Gaudino]

We have some source files which contain comments not associated with any code, this is common in ExtJS code, please see https://docs.sencha.com/extjs/7.4.0/classic/src/ComboBox.js.html#Ext.form.field.ComboBox-event-select

The error we have is this:

ERROR in ./docs/js_docs_student/overwrites/Select2.md

Module build failed (from ./node_modules/@docusaurus/mdx-loader/lib/index.js):
SyntaxError: /home/anthony/safe_docs/safe/docs/docs/js_docs_student/overwrites/Select2.md: Expected corresponding JSX closing tag for <a>. (39:28)

  37 | you cannot use the Next button to get to this select field. This functionality works as expected on iOS.event_">"focus
  38 | Fires when this field receives input focus. This happens both when you tap on the field and when you focus on the field by using
> 39 | next or tab on a keyboard.`}</p>
     |                             ^
  40 | <p>{`Please note that this event is not very reliable on Android. For example, if your Select field is second in your form panel,
  41 | you cannot use the Next button to get to this select field. This functionality works as expected on iOS." (this, e)`}</a></dt></p>
  42 | <dd></dd>
    at Object._raise (/home/anthony/safe_docs/safe/docs/node_modules/@babel/parser/lib/index.js:541:17)
    at Object.raiseWithData (/home/anthony/safe_docs/safe/docs/node_modules/@babel/parser/lib/index.js:534:17)
    at Object.raise (/home/anthony/safe_docs/safe/docs/node_modules/@babel/parser/lib/index.js:495:17)
    at Object.jsxParseElementAt (/home/anthony/safe_docs/safe/docs/node_modules/@babel/parser/lib/index.js:7439:16)
    at Object.jsxParseElementAt (/home/anthony/safe_docs/safe/docs/node_modules/@babel/parser/lib/index.js:7407:32)
    at Object.jsxParseElementAt (/home/anthony/safe_docs/safe/docs/node_modules/@babel/parser/lib/index.js:7407:32)
    at Object.jsxParseElementAt (/home/anthony/safe_docs/safe/docs/node_modules/@babel/parser/lib/index.js:7407:32)
    at Object.jsxParseElement (/home/anthony/safe_docs/safe/docs/node_modules/@babel/parser/lib/index.js:7465:17)
    at Object.parseExprAtom (/home/anthony/safe_docs/safe/docs/node_modules/@babel/parser/lib/index.js:7472:19)
    at Object.parseExprSubscripts (/home/anthony/safe_docs/safe/docs/node_modules/@babel/parser/lib/index.js:11584:23)
    at Object.parseUpdate (/home/anthony/safe_docs/safe/docs/node_modules/@babel/parser/lib/index.js:11564:21)
    at Object.parseMaybeUnary (/home/anthony/safe_docs/safe/docs/node_modules/@babel/parser/lib/index.js:11539:23)
    at Object.parseMaybeUnaryOrPrivate (/home/anthony/safe_docs/safe/docs/node_modules/@babel/parser/lib/index.js:11353:61)
    at Object.parseExprOps (/home/anthony/safe_docs/safe/docs/node_modules/@babel/parser/lib/index.js:11360:23)
    at Object.parseMaybeConditional (/home/anthony/safe_docs/safe/docs/node_modules/@babel/parser/lib/index.js:11330:23)
    at Object.parseMaybeAssign (/home/anthony/safe_docs/safe/docs/node_modules/@babel/parser/lib/index.js:11290:21)

Here's a minimal file which causes the issue:

Ext.define('Ext.field.Select2', {
   /**
    * @event change
    * Fires when an option selection has changed
    * @param {Ext.field.Select} this
    * @param {Ext.data.Model} newValue The corresponding record for the new value
    * @param {Ext.data.Model} oldValue The corresponding record for the old value
    */

   /**
    * @event focus
    * Fires when this field receives input focus. This happens both when you tap on the field and when you focus on the field by using
    * 'next' or 'tab' on a keyboard.
    *
    * Please note that this event is not very reliable on Android. For example, if your Select field is second in your form panel,
    * you cannot use the Next button to get to this select field. This functionality works as expected on iOS.
    * @param {Ext.field.Select} this This field
    * @param {Ext.event.Event} e
    */
});

The result Markdown file is this:

## Events

<dl>
<dt><a href="#change
Fires when an option selection has changedevent_">"change
Fires when an option selection has changed" (this, newValue, oldValue)</a></dt>
<dd></dd>
<dt><a href="#focus
Fires when this field receives input focus. This happens both when you tap on the field and when you focus on the field by using
next or tab on a keyboard.

Please note that this event is not very reliable on Android. For example, if your Select field is second in your form panel,
you cannot use the Next button to get to this select field. This functionality works as expected on iOS.event_">"focus
Fires when this field receives input focus. This happens both when you tap on the field and when you focus on the field by using
next or tab on a keyboard.

Please note that this event is not very reliable on Android. For example, if your Select field is second in your form panel,
you cannot use the Next button to get to this select field. This functionality works as expected on iOS." (this, e)</a></dt>
<dd></dd>
</dl>

<a name="change
Fires when an option selection has changedevent_"></a>

## "change
Fires when an option selection has changed" (this, newValue, oldValue)
**Kind**: event emitted  

| Param | Type | Description |
| --- | --- | --- |
| this | <code>Ext.field.Select</code> |  |
| newValue | <code>Ext.data.Model</code> | The corresponding record for the new value |
| oldValue | <code>Ext.data.Model</code> | The corresponding record for the old value |

<a name="focus
Fires when this field receives input focus. This happens both when you tap on the field and when you focus on the field by using
next or tab on a keyboard.

Please note that this event is not very reliable on Android. For example, if your Select field is second in your form panel,
you cannot use the Next button to get to this select field. This functionality works as expected on iOS.event_"></a>

## "focus
Fires when this field receives input focus. This happens both when you tap on the field and when you focus on the field by using
next or tab on a keyboard.

Please note that this event is not very reliable on Android. For example, if your Select field is second in your form panel,
you cannot use the Next button to get to this select field. This functionality works as expected on iOS." (this, e)
**Kind**: event emitted  

| Param | Type | Description |
| --- | --- | --- |
| this | <code>Ext.field.Select</code> | This field |
| e | <code>Ext.event.Event</code> |  |

**documentation generated on Thu, 09 Dec 2021 13:01:03 GMT**

I'm using the example plugin which adds the date.

[fabienwnklr]

Hi, i have same issue, some fix or solutions? thanks !

[namti]

I have the similar issue. In my case, I use MDX v2. The issue is that the markdown generated has mixed inline and block with the same tag.

https://github.com/orgs/mdx-js/discussions/2260

[75lb]

Hi, I don't recognise this syntax error - it's not an exception thrown by jsdoc-to-markdown:

SyntaxError: /home/anthony/safe_docs/safe/docs/docs/js_docs_student/overwrites/Select2.md: Expected corresponding JSX closing tag for <a>. (39:28)

I scanned your log output and I see other apps: docusaurus and mdx - I had never heard of these apps until now..

The issue title is "jsdoc-to-markdown generates invalid Markdown" - jsdoc2md outputs Github-Flavoured Markdown specifically.. does using the jsdoc2md --no-gfm option help?

  --no-gfm                            By default, dmd generates github-flavoured markdown. Not all markdown parsers
                                      render gfm correctly. If your generated docs look incorrect on sites other
                                      than Github (e.g. npmjs.org) try enabling this option to disable Github-
                                      specific syntax.

What is your desired outcome for this issue, what do you need to change in the jsdoc2md output?

[malouro]

Had a similar issue in a project where we're generating markdown for usage in a Storybook and writing it out as .mdx.

Unfortunately, the generated output is not valid MDX (I think for any version of MDX that is 2+ ?) because of something akin to what's detailed in this issue, using --no-gfm does not resolve this.

Example of what we have generating currently:

<dl>
<dt><a href="#getDateLocale">getDateLocale</a> ⇒ <code>string</code></dt>
<dd><p>summary goes here</p>
</dd>
</dl>

What would be valid in our use case:

<dl>
<dt><a href="#getDateLocale">getDateLocale</a> ⇒ <code>string</code></dt>
<dd>
<p>summary goes here</p>
</dd>
</dl>

(Or this is also valid)

<dl>
<dt><a href="#getDateLocale">getDateLocale</a> ⇒ <code>string</code></dt>
<dd><p>summary goes here</p></dd>
</dl>

Basically, MDX does not accept mixing inline or block syntax for the same tag.

I've gotten around this by running the generated .md(x) file through Prettier, or some other formatting tool could also work probably.