docs: implement docs lint

[hunterachieng]

Summary

Implement @mdx-js/mdx to lint docs during build

Fixes #1241

Details

Add technical details of what you've changed (and why).

AI Usage

Please disclose how you've used AI in this work (it's cool, we just want to
know!):

• Code generation (copilot but not intellisense)
• Learning or fact checking
• Strategy / design
• Optimisation / refactoring
• Translation / spellchecking / doc gen
• Other
• I have not used AI

You can read more details in our
Responsible AI Policy

Review Checklist

Before merging, the reviewer should check the following items:

• Does the PR do what it claims to do?
• If this is a new adaptor, added the adaptor on marketing website ?
• If this PR includes breaking changes, do we need to update any jobs in
  production? Is it safe to release?
• Are there any unit tests?
• Is there a changeset associated with this PR? Should there be? Note that
  dev only changes don't need a changeset.
• Have you ticked a box under AI Usage?

[josephjclark]

@hunterachieng this looks like a great start.

How do we configure linting rules? Is there a config file we can set up?

When I run right now, I get errors like this in a bunch of adaptors:

❌ Error in tmp/rapidpro/docs/index.md:
Expected the closing tag `</dt>` either after the end of `paragraph` (3:64) or another opening tag after the start of `paragraph` (3:5)

I don't think the docusaurus build is throwing this error - if it was, the docs wouldn't be building.

So we've worked out a solution to run linting, that's great! How do we ensure consistent rules with the docs repo?

Maybe a good acceptance criteria is:

• There are no errors in linting in adaptors
• We can load docs.json into the docs repo without error
• Then we can re-create one of Taylor's original failures (referenced in the issue)
• Then we should see linting fail here in adaptors
• And if we try to load into docs, we should see the fail duplicated

[hunterachieng]

@josephjclark when I use @mdx-js/mdx, it flags all the lint issues. If I use remark, it passes but omits all the docs with errors. The section with an error is not included in the .md.
I used AI to try and understand how docusaurus handles its linting and some of the libraries it uses do not flag the closing tag issue we are facing with jsx.
The two libraries I used both exist in our docs repo, but I am unable to replicate the error fully.

[josephjclark]

Hmm. If we can't get consistent linting then there's sadly no point in doing this work (we'll just have to be vigilant and manually check that the docs build passes)

Looking at https://www.npmjs.com/package/@mdx-js/mdx#architecture it feels like this is a quite a complicated compilation process. But there must be a way to configure standards.

If you go to docusaurus, are you able to find docs or issues which explain how to configure linting rules?

[hunterachieng]

@josephjclark I have checked docusaurus and they have this playground for checking if your .md is correct. I used it with our dhis2 docs and it failed

[josephjclark]

@hunterachieng setting the input format to markdown (not mdx) in that online mdx parser will allow the parser to run. But I'm not sure what that's telling us.

The markdown we generate is technically fine. We know that because we can build the docsite from it.

The problem is that there's some strictness somewhere in the parsing process that is failing because, for example, closing HTML elements aren't on a new line (ie, bad formatting in the markdown).

So we need to work out how to get that same strictness in adaptors. Or I suppose find out how to make docs a little bit more lenient.

I think this requires more investigation. We should put the issue into Blocked until we can find more time to investigate (I can't spend any time on this this week)

@martalovescoffee I can't access zenhub, can you mark this is blocked for me? Thanks!

[hunterachieng]

@josephjclark since we moved this to blocked, I am turning this into a draft PR until we get back to it