Inconsistencies in Markdown Formatting

[furtni]

While working on #275 I came across a few things I would like to discuss.

Prettier vs. Markdownlint

As per .vscode/extensions.json both Prettier and markdownlint are recommended extensions. I assume their usage is encouraged?

The indent_size = 4 specified in .editorconfig is respected by Prettier, since it parses it into it's own config.
However, the default rule-set of markdownlint is not compatible with the resulting format.

This causes linting issues after formatting with Prettier, especially with nested lists mixing unordered and ordered list:

I tried to define a compatible ruleset as suggested here.

.markdownlint.json:

{
  "list-marker-space": {
    "ul_multi": 3,
    "ul_single": 3
  },
  "ul-indent": {
    "indent": 4
  }
}

Yet, this does not solve the issue. Even with manually tweaking the rules values:

It seems to me that Prettier uses more complex conditional formatting than what can be specified with markdownlint's rule-sets.

Current State

Currently almost none of the markdown files in this repository conform to either format:

$ prettier -c ./content
Checking formatting...
[warn] content/de/_index.html
...
[warn] content/en/storage-backup/s3-storage/tutorials/versioning-in-s3.md
[warn] Code style issues found in 524 files. Run Prettier with --write to fix.

$ markdownlint-cli2 "./content/**/*.md" 2> /dev/null
markdownlint-cli2 v0.17.2 (markdownlint v0.37.4)
Finding: ./content/**/*.md
Linting: 586 file(s)
Summary: 7784 error(s)

Suggestions

If we want to enforce consistent formatting I would suggest that we:

• Choose one of Prettier/markdownlint. (Or discover a solution I didn't find.)

• Don't have the rules inferred by letting the formatter parse the .editorconfig. This is really annoying to debug.
  Explicitly specify the formatting rules in an appropriate configuration file for the formatter.
  Be it a .markdownlint.json or a .prettierrc.

• Don't set the extension as recommended, but preinstall it via devcontainer.json:

  "customizations": {
    "vscode": {
      "extensions": [
        "esbenp.prettier-vscode"
      ],
      "settings": {
        "[markdown]": {
          "editor.defaultFormatter": "esbenp.prettier-vscode",
          "editor.formatOnSave": true // This might be a little too intrusive for some?
        }
      }
    }

• Maybe even add a lint job to the existing workflows?
  This would guarantee only properly formatted code being merged.

  - name: Check Markdown format
    uses: creyD/prettier_action@v4.3
    with:
      dry: true
      prettier_options: --check ./content/**/*.md

Conclusion

I think that to conform to what we defined for ourselves in ./guidelines, we need to ensure a consistent style/format.

Let me know what you think and feel free to suggest entirely different approaches.

[saschascherrer]

Hi @furtni,
I agree that the discrepancies you mentioned should be resolved.

I also agree, that there is not much value in using two different tools for the same job.
I would prefer prettier as it seems to support more fine-grained style definitions.
As soon as we derive a decision on which tool to use, I would be happy to add a CI-Step to help ensure conformant formatting.