Include custom rules in extension

[mschoettle]

I am trying to use markdownlint (and markdownlint-cli2) for a project and would like to have a setup where the vscode extension, pre-commit and markdownlint-cli2 provide consistent results. This works generally fine. However, I would like to include a custom rule.

.markdownlint-cli2.yaml:

customRules:
  # Enforce one sentence per line
  # See: https://github.com/DavidAnson/markdownlint/pull/719
  - "markdownlint-rule-max-one-sentence-per-line"

.pre-commit.config.yaml (excerpt):

  - repo: https://github.com/DavidAnson/markdownlint-cli2
    rev: v0.13.0
    hooks:
      - id: markdownlint-cli2-rules-docker

I added the following lines to .vscode/settings.json:

"markdownlint.customRules": [
      "{aepfli.markdownlint-rule-max-one-sentence-per-line}/npm/rule/package",
    ]

My initial assumption was that vscode/the extension would then install this package. However, based on what I understand after some investigation this is not the case.

Since there is a supplementary Docker image that includes custom rules I wonder if it would be possible to include the same custom rules in the vscode extension?

[DavidAnson]

Whatever configuration works for CLI2 should automatically work for the extension in Code (when running locally). I assume the custom rule package/code is available locally to CLI2, so would assume that it should be usable from that same location by the extension. Why does that not work?

[mschoettle]

Hm. So I have not installed anything locally. It wasn't necessary before. Both the pre-commit hook and the vscode extension work without installing anything manually.

In this particular case, pre-commit runs it in a container (to use the supplementary image).

I assume the vscode extension comes shipped with CLI2, right?

[DavidAnson]

The extension extends (not includes) CLI2. I see now that you are using Docker for pre-commit, does that mean you are also using Docker for your CLI2 scenario? If so, then I see why you do not need to install the rule as it is included with the "rules" container image. (To be clear, do you have three scenarios or two? I understood that you were using pre-commit, the extension, and CLI2 directly, but perhaps the latter was a misunderstanding.)

I would rather not include third-party rules with the extension bundle because I don't want to be responsible if they misbehave. In the case of Docker, there was a straightforward way to have a container image for the stuff I support and then toss the extra rules in a derivative container image. I don't think there is a clear way to do that for the extension. Complicating matters, when the extension is used on the web, various parts of basic Node functionality are not present. I have done quite a lot of work to make sure the extension can run in that scenario and I am not prepared to do the same for custom rules.

[mschoettle]

The extension extends (not includes) CLI2. I see now that you are using Docker for pre-commit, does that mean you are also using Docker for your CLI2 scenario? If so, then I see why you do not need to install the rule as it is included with the "rules" container image. (To be clear, do you have three scenarios or two? I understood that you were using pre-commit, the extension, and CLI2 directly, but perhaps the latter was a misunderstanding.)

I have currently two scenarios: writing/editing in the IDE and pre-commit. There might be a third scenario which is running it in CI but I may be calling pre-commit in the CI job instead of CLI2 directly.

I would rather not include third-party rules with the extension bundle because I don't want to be responsible if they misbehave. In the case of Docker, there was a straightforward way to have a container image for the stuff I support and then toss the extra rules in a derivative container image. I don't think there is a clear way to do that for the extension. Complicating matters, when the extension is used on the web, various parts of basic Node functionality are not present. I have done quite a lot of work to make sure the extension can run in that scenario and I am not prepared to do the same for custom rules.

I understand. Although it is unfortunate since it makes having a consistent setup across the different scenarios difficult (at least when using custom rules, without them it works fine).

One option might be to only use custom rules with pre-commit and not use them in the IDE, at the cost of user experience.

What would be the recommended way to ensure the extension can find a desired custom rule package? Installing the package locally and pointing the extension to the path in the customRules vscode setting?

[DavidAnson]

What would be the recommended way to ensure the extension can find a desired custom rule package? Installing the package locally and pointing the extension to the path in the customRules vscode setting?

That should work, but may be complicated by also having that rule in the configuration file.

[mschoettle]

I am able to use the rule just in CI by having a second .markdownlint-cli2.yaml file in a sub-directory. I path that config file to markdownlint-cli2 with the --config argument and it extends the config in the root of the project.

I am wondering if it is possible to put the custom rule into the root config and configure the vscode extension to disable it. Is this possible? That way it would be used in pre-commit and CI.

[DavidAnson]

I'm not sure how one would do that with JSON or YAML, but if you don't mind using JS for your configuration file, it may be able to run some code to detect whether it's running in the CI or Code scenario and return a different configuration object with or without the custom rule.

[SimonEismann]

I hit a similar issue as described here, where custom rules make the markdownlint workflow less smooth:

• Without any custom rules, developers can simply install the vs code extension, install the pre-commit hooks, and they are good to go.
• With one or more custom rules, both the vscode extension and the pre-commit hooks fail because of the missing package.

To make the custom rules workflow as smooth as the normal workflow would require getting the vscode extension, pre-commit hooks, and potentially the cli2 to install the custom rules packages automatically, which seems quite challenging/high-effort. Maybe an alternative would be to graduate popular custom rule , such as markdownlint-rule-titlecase and markdownlint-rule-relative-links to the main repo?