How to configure remark-lint list-item-indent in codacy.yml?

Can someone help me change the default markdown spacing between a list item bullet and its content? It’s currently set to three spaces (who does that?), while I only want one.

I’ve looked at the Codacy documentation around this, but I still find it unclear. I’ve tried various combinations of things in my .codacy.yml file to no avail. For example:

---
engines:
  remark-stringify:
    listItemIndent: space

I’ve tried many other options, like remark-lint instead of remark-stringify, and one or 1 for listItemIndent. I’m starting to pull out my hair. Help?

Hello @humblehacker, and welcome to the Codacy Community! :wave:

I’ll assume that you’re not using a remark-lint configuration file on your repository (let me know if this isn’t your scenario). In this case, you can change the code pattern directly on the Codacy UI:

  1. Open your repository Code patterns page and click the tool remark-lint.
  2. Find the code pattern “Warn when the spacing between a list item’s bullet and its content violates” and click Show details.
  3. Set the parameter remark-lint-list-item-indent to space.
  4. You may want to reanalyze your repository at this stage just to ensure that Codacy no longer reports the issue.

:arrow_right: Having explained this, my personal recommendation is to turn off remark-lint and use the tool markdownlint instead:

  • I find that remark-lint has too many rules that are hard to understand and configure, and that don’t add any meaningful value to your Markdown editing workflow.
  • markdownlint, on the contrary, has a sensible list of rules that are well-documented are easy to set up.

Just one final remark regarding why it could be preferable to indent the content using 4 spaces as explained on the markdownlint docs:

Indenting by 4 spaces is consistent with code blocks and simpler for editors to implement. Additionally, this can be a compatibility issue for other Markdown parsers, which require 4-space indents. More information: Markdown Style Guide - Ciro Santilli and Marked: Discussion.

Let us know if this helps!

Thanks for your detailed reply! Is there no way to make this change in .codacy.yml?

The .codacy.yml is the Codacy configuration file, which allows performing some advanced configurations but not configuring the actual code patterns of the tools.

What you probably want to do is to use the specific configuration file for remark-lint:

  1. Create a remark-lint configuration file on the root of your repository, for instance .remarkrc.

  2. After pushing this file to the remote default branch of your repository, open the Code patterns page, select the remark-lint tool, and select Configuration file.

    From this point on, Codacy will run remark-lint using the settings that you define on the .remarkrc.yaml exclusively, instead of the settings defined on the Codacy UI.

With remark-lint, actually setting up the .remarkrc is once again the tricky bit. :wink: You can use this old configuration file that we used on the codacy/docs repository as an example to get started (the configuration file uses a couple of presets and overwrites only a couple of settings from those presets). To adjust the list item indentation like you originally asked, you must also configure the rule remark-lint-list-item-indent and the full configuration file will become:

{
  "settings": {
    "incrementListMarker": false
  },
  "plugins": [
    "preset-lint-consistent",
    "preset-lint-recommended",
    "lint-heading-increment",
    [
      "lint-unordered-list-marker-style", "-"
    ],
    [
      "lint-ordered-list-marker-value", "one"
    ],
    [
      "remark-lint-list-item-indent", "space"
    ]
  ]
}

If you consider using markdownlint instead, the configuration is similar but you’ll use the markdownlint configuration file .markdownlint.json instead. Here’s the official template or the current configuration file we’re using on codacy/docs to get you started.