Just had an idea: as a follow-up to this, we could also enforce that every rule option has an ❌ Incorrect / ✅ Correct tab group, the way many do in docs today...

I wonder if we can rework our docs to be generated from json or something?

It would be much easier to enforce the structure rather than trying to parse unstructured markdown.

Or perhaps we put things across multiple files or something? Could enforce one folder per option then.

That's interesting. I do like how we have raw .mdx files - it means we can integrate with raw .mdx tooling... will need to think on this a bit.

Perhaps we can define separate MDX files on disk?
Then the root docs would just be some sort of file that just imports a bunch of other MDX files to render them?

If we enforce one file per section then it's pretty easy to even just automatically merge them into a single file - eg enforce naming like 1_Rule_Details.mdx, 2_Options.mdx, etc and then a simple fs folder read gives you the sections and their order to concatenate the files in for the final rule doc page?

You can directly import MDX:

import Options from "./1_Options.mdx";

## Options

<Options />

No need to wire your own concatenation/fs reading infra.

However I'm -1 on splitting the files unless we plan to reuse them. Validation is a better idea to me because then we can more easily discover exceptions (there will always be exceptions where the structure doesn't apply, I'm sure).

My issue is that vidation right now is a complete head fuck because everything is unstructured.

So it's all about fuzzily grouping paragraphs together based on heading positions - it's disgusting.

then we can more easily discover exceptions

Isn't it the opposite? It would be harder to discover exceptions because the single file is unstructured and thus exceptions will silently fall through.

With split files I'd have thought exceptions would be more obvious because the boxes are more rigid.

Isn't it the opposite? It would be harder to discover exceptions because the single file is unstructured and thus exceptions will silently fall through.

No; with validation, you would encode all exceptions as a list. With your own Markdown structure it would be hard to discover them because you can't easily filter for "files not containing a particular pattern".

With validation:

<!-- rule-name.md -->
## Options

...

### `foo`

...

### `bar`

...

// Validator.ts
const noOptionsHeading = new Set(["a", "b"]);
if (noOptionsHeading.has(file.name)) return;
const subheadings = file.ast.getSubheadings("Options");
if (!subheadings) throw new Error("Missing options");
const optionsUnstructured = new Set(["c", "d"]);
if (optionsUnstructured.has(file.name)) return;
const missingHeadings = rule.options.map((o) => o.name).filter((n) => !subheadings.includes(`\`${n}\``));
if (missingHeadings.length) throw new Error(`Missing headings for ${missingHeadings.join(", ")}`);

With subpages:

<!-- rule-name.md -->
## Options

import Options from "./options.mdx";

<Options />

// Validator.ts
const optionsSubfile = getOptionsSubfile("rule-name");
const subheadings = optionsSubfile.ast.getHeadings();
if (!subheadings) throw new Error("Missing options");
const optionsUnstructured = new Set(["c", "d"]);
if (optionsUnstructured.has(file.name)) return;
const missingHeadings = rule.options.map((o) => o.name).filter((n) => !subheadings.includes(`\`${n}\``));
if (missingHeadings.length) throw new Error(`Missing headings for ${missingHeadings.join(", ")}`);

The bulk of the validation logic (i.e. finding subheadings) is still there, unless you actually plan to make each option subheading (foo/bar) its own page.

FWIW, I already built similar validation logic for MDN. You can take a look at https://github.com/jc-verse/mdn-checker/blob/master/packages/mdn-checker/src/rules/heading.ts and https://github.com/jc-verse/mdn-checker/blob/master/packages/mdn-checker/src/rules/syntax-section.ts. The heading-discovery logic is here: https://github.com/jc-verse/mdn-checker/blob/master/packages/mdn-checker/src/utils.ts#L172-L197

Proposal: can we:

1. Accept this issue's proposal of all options having a heading
2. File a followup around investigating a different mdx strategy

? I think it'd be good to accept this & get #8015 into review as part of (1), before (2).

If it wasn't clear - yes I'm in favour of this.