Questions about proper configuration

[germanfrelo]

Hi David.

First of all, thanks for this great project!

I'm new to markdownlint and I have a few questions about the proper configuration of this extension.

When using this extension, be alone or together with the markdownlint-cli2 package installed as a dependency of the repository, will all rules be applied with their default values even without having a config file in the repo (e.g. .markdownlint-cli2.jsonc)?

Will some of markdownlint's default rule values be overridden by an .editorconfig file with these options (example)?

root = true

[*]
# another options here
indent_style = tab

[*.md]
indent_style = space
indent_size = 2
trim_trailing_whitespace = false

I say this because I've seen that the mdn/content repo uses markdownlint-cli2 and has this in its .editorconfig file. Is that necessary?

And what about having the same options in the VS Code settings?

{
  "editor.insertSpaces": false,
  "editor.tabSize": 4,
  "[markdown]": {
    "editor.insertSpaces": true,
    "editor.tabSize": 2,
    "files.trimTrailingWhitespace": false
  }
}

Finally, I would like to suggest adding this to the Using markdownlint with Prettier doc:

{
  "[markdown]": {
    "editor.defaultFormatter": "DavidAnson.vscode-markdownlint",
  }
}

I'm saying this because I tested your demo with the Prettier extension installed and set it as the default formatter ("editor.defaultFormatter": "esbenp.prettier-vscode"), but without the above setting the editor uses Prettier to format the file. Maybe this was obvious, but not to me…

[DavidAnson]

Yes, rules are applied with their default settings when no configuration file is present.

.editorconfig is not supported. there is a different issue with some more context around that.

Precedence of configuration sources is described at the bottom of this section: https://github.com/DavidAnson/vscode-markdownlint?tab=readme-ov-file#markdownlintconfig

The document about interoperating with Prettier is in the library repository, so doesn't talk about VS Code integration. It's mainly about avoiding configuration conflicts - people can use whatever formatter they prefer.

[germanfrelo]

Yes, rules are applied with their default settings when no configuration file is present.

Ah, ok. So it's not explicitly mentioned in the documentation, it's just assumed?

.editorconfig is not supported. there is a different issue with some more context around that.

Is this the issue? https://github.com/DavidAnson/markdownlint-cli2/issues/179

Just to be sure, what do you mean by ".editorconfig is not supported"? If I understand correctly, markdownlint does not parse .editorconfig to set some rules from there. But what I wanted to express is that setting some options in .editorconfig does override some default markdownlint rules (even if Prettier is not installed/used). Is this the expected behavior? I just created a demo repo if it helps.

[DavidAnson]

So it's not explicitly mentioned in the documentation, it's just assumed?

That's pretty much what "default" means, but I don't see that I have spelled it out directly.

Is this the issue? DavidAnson/markdownlint-cli2#179

Yep!

If I understand correctly, markdownlint does not parse .editorconfig ...

Right. This library does not use that file at all and its content has no effect on linting behavior. If you are seeing any behavioral changes as a result of that file, it is probably due to the other extension you have configured in the demo repository or perhaps VS Code itself.

[germanfrelo]

Ok, thank you for your time.

[germanfrelo]

If I understand correctly, markdownlint does not parse .editorconfig ...

Right. This library does not use that file at all and its content has no effect on linting behavior. If you are seeing any behavioral changes as a result of that file, it is probably due to the other extension you have configured in the demo repository or perhaps VS Code itself.

I see behavioral changes. This is the setup I'm using:

• All my VS Code extensions are disabled for the current workspace, except:

  • markdownlint
  • EditorConfig (required to use EditorConfig with VS Code)

• VS Code workspace settings: all the default ones (copied from Preferences: Open Default Settings (JSON)), plus these additions:

  "editor.codeActionsOnSave": {
  "source.fixAll.markdownlint": "explicit"
  },
  "editor.formatOnSave": true,
  "editor.renderWhitespace": "boundary" // to see trailing whitespace characters

• This .editorconfig file:

  root = true
  
  [*]
  charset = utf-8
  end_of_line = lf
  insert_final_newline = true
  trim_trailing_whitespace = true
  indent_style = tab

• This Markdown file (not yet saved):

  # Heading  
  
  Paragraph  
  Paragraph
  
  - list item
  - list item

When I save the Markdown file, trailing whitespace is removed from Heading and first Paragraph (thus not respecting the default markdownlint rule that allows 2 trailing spaces):

# Heading

Paragraph
Paragraph

- list item
  - list item

Also, before saving, I indented the second list item by pressing Tab, but 1 tab character was added (because of indent_style = tab) instead of space(s), thus not respecting the default markdownlint rules of no hard tabs and 2-space indentation for unordered lists. However, the indentation is converted to 2 spaces when I save.

If the contents of .editorconfig have no effect on linting behavior, why doesn't it respect these rules?

I need to add these properties to .editorconfig so that markdownlint rules are respected:

[*.md]
trim_trailing_whitespace = false
indent_style = space

[DavidAnson]

From what I can tell, you have set up the .editorconfig file to remove trailing white space and the Editor Config extension that you installed is doing exactly that. You seem to also want it to respect your Markdown linting configuration (allowing exactly two trailing spaces), but the documentation for that project seems to make no claims that it is aware of or respects markdownlint. If you think the EditorConfig project should behave differently, please open an issue in their issue tracker.

You should be able to confirm this by uninstalling or disabling the markdownlint extension and trying the behavior above.

If you want to use both extensions together, you'll need to configure them in ways that do not conflict.