Linter does not ignore MDX content beyond simple tags

[mghill]

Referring to this commit, the linter finds issue with the imports at the top (which can presumably be wrapped in a tag of some sort?), and the Tabs declaration on line 21 (which is only slightly more complex than an open/close tag) . The closing tags etc have no issues.

[kimburgess]

This is due to the current parser only supporting markdown, as opposed to MDX.

A quick solution should be possible via the pre-existing filter-rule-allow-list. This can be configured with a set of RegExp's that matches the import statements, as well as anything resembling JSX components.

A nicer / long term solution will likely be a mdx plug-in. There are existing ones for both html and JSX which may provide useful references.

I'll get the filter-rule approach up and running, then we can go down that second route if there's anything that can't be expressed that way, or there's another need for it.

[kimburgess]

After sleeping on this - do we actually want/need to mix in MDX here at all?

Doing so leaks pieces of the docs renderer into the docs content. Looking through the current set of MDX features in Docusaurus, Tabs look to be the only item that introduces this. Admonitions, live code blocks and the other features are all just vanilla markdown with some overloaded syntax (which is still readable in raw form too).

Tabs are definitely important as they will help with progressive disclosure and keep things neat—definitely not advocating for their removal, maybe just an alternative implementation.

There is a rather useful HTML element that provides similar functionality: details.

Writing this:

<details>
    <summary>Details</summary>
    Something small enough to escape casual notice.
</details>

Creates this:

Details

Something small enough to escape casual notice.

The docs renderer can then be updated to transpile this into the Docusaurus Tab component so the end result there is still the same, but then this also stays readable if viewed elsewhere.

[kimburgess]

Closing. Linter is working correctly for markdown content, but correctly erroring when passed mdx.

Solution to support tab groups via PlaceOS/docs-site#13.