Implement overrides similar to ESLint

[remcohaszing]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and couldn’t find anything (or linked relevant results below)

Problem

Sometimes certain checks depend on context, not just language.

For example, typically markdown documents need to contain complete and valid markdown documents. Some specific documents may need some specific checks to be included or excluded though. For example:

• MDX files need additional plugins to enhance the parser
• GitHub issue templates may not use newlines inside paragraphs
• Email templates might not need a level 1 heading

Solution

ESLint has pretty much the exact problem. They solved it using overrides

The same could be done for unified-engine. For example:

plugins:
  - remark-gfm
  - [remark-lint-first-heading-level, 1]
overrides:
  - files: ['*.mdx']
    plugins:
      - remark-mdx
  - files: [.github/]
    plugins:
      - [remark-lint-first-heading-level, false]

ESLint also uses the globs to determine additional file extensions to check.

Alternatives

I can’t really think of anything else

[wooorm]

• Your example makes a lot of sense, something like it has been asked somewhere before as well.
• It’s possible to place different RC files in different folders, how does this interfere with that?
• What about plugin order? Especially as remark could be used with, say, remark-rehype, to switch to another format.

[remcohaszing]

• It’s possible to place different RC files in different folders, how does this interfere with that?

I don’t know. Perhaps we should have a look at how ESLint handles it.

• What about plugin order? Especially as remark could be used with, say, remark-rehype, to switch to another format.

I think override means the override takes precedence over the original value, including any options. The fact that remark-rehype transforms the AST significantly or has bridge and mutate mode is a detail. Also I don’t think remark-rehype should typically be used with unified-engine. It’s a bit annoying for remark-retext though, but I don’t think it’s likely users will want to apply different retext rules depending on context. Even if they do, it could be overridden programmatically.

const retextPlugins = [
  [someRetextPlugin]
]

export default {
  plugins: [
    ['remark-retext', unified().use(retextPlugins)]
  ],
  overrides: [
    files: ['*.mdx'],
    plugins: [
      ['remark-retext', unified().use([...retextPlugins, anotherRetextPlugin])]
    ],
  ]
}

[wooorm]

It’s possible to place different RC files in different folders, how does this interfere with that?

I think this point won’t need any special handling. It’ll just work.
Assuming a user has multiple config files, then they already dealt with them replacing instead of extending each other.
Say there’s a config in a monorepo, and one in a subpackage, then the user would presumably understand that overrides for certain files need to be in their closest config file?

---

Also I don’t think remark-rehype should typically be used with unified-engine

I’m not so sure.
At least I find it an an important case to support properly.
Maybe, similar to how config files override (replace) each other instead of merge, the same should occur with overrides too? Replace instead of merge.

---

One even bigger problem I didn’t think of: config files are also presets. 😬 Config files and presets can be loaded from say node_modules. 😬

[wooorm]

I no longer think this can go somewhere.

Configs are presets. Except that strings are allowed instead of functions.

Presets (and config) are applied to unified processors.

It would mean things are loaded, such as remark-mdx in these examples, even though they are not used.

That may not be so bad for a CLI. But is more bad in things like react-markdown.

One way to sidestep that is to diverge further, between config files and presets. To allow overrides only in config files.
But instead of that, I’d rather do the inverse: to remove config files with strings. To only allow sharable presets.

---

Practical suggestions for the examples in the OP:

a) MDX files need additional plugins to enhance the parser

remark-mdx also applies to the serializer; there are also differences in lint rules; and, perhaps plugins would be configured differently, when components are supported instead of raw HTML?

Markdown vs MDX is one axis, but there are many more. Think files that are “partials”—to be imported into others.

I think different config files can work here.

b) GitHub issue templates may not use newlines inside paragraphs

Then use a config file that extends.
Though: newlines in paragraphs are fine? 🤔 I think you mean that things look better if you do not line wrap markdown because GH turns things into hard breaks?

c) Email templates might not need a level 1 heading

Same, either put the email templates in a folder. Or: use a comment in particular files.