How can I configure Prettier to preserve setext headings ("===") instead of converting them into ATX headings ("#")?

Question

When I write a .md file with VS Code and I save, it automatically formats my code. While this is generally what I want, the formatting it uses bothers me.

For instance, I like to have control over two things:

• I like to do my h1 titles using === separator below the title
• I like to control how many carriage return I have between sections of my file

but every time I save, all my manual formatting disappears and vscode reformats like this:

• all my h1 titles use the # prefix instead of the = notation
• there is always exactly one line in-between each section, which makes it harder to read imho

Is it possible to configure vscode/prettier to stop those kind of formatting, while keeping the format on save feature?

Or can I just disable prettier for .md files?

Answer 1

I actually added this in my settings.json, and it worked:

"[markdown]": {
    "editor.formatOnSave": false,
}

Actually disabling the format on save, and now i have complete control over my markdown file formatting again :)

Answer 2

If you google "github prettier issues markdown heading", you'll find that configuring to preserve setext headings/titles instead of converting them into ATX ones is not supported by Prettier at the time of this writing: Support setext headings in Markdown #6013. You can give that issue ticket a thumbs up to show support for it and subscribe to it to get notified about discussion and progress. Please avoid making noisy comments there like "+1" / "bump".

Someone noticed that if you split the title into multiple lines, then Prettier won't convert the setext format into ATX format (source), but this a pretty ugly hack.

In the meantime, you could take the rage-quit route and disable format-on-save for Markdown files in VS Code using the following in your settings.json:

"[markdown]": {
    "editor.formatOnSave": false,
}

Answer 3

Prettier defines itself as being opinionated. In practice, this means it doesn't really support configuration. As such, if your formatting requirements don't align with theirs, it's not a suitable tool for your needs. In addition, there has been an issue open with their team about this particular issue for over four years, so the team doesn't seem particularly responsive to this specific request.

If you want to continue using Prettier for other languages, you can disable it for Markdown with this setting in .vscode/settings.json:

{
  "prettier.disableLanguages": [
    "markdown"
  ]
}

You can then enable a more flexible formatting extension:

{
  "markdownlint.config": {
    "header-style": {
      "style": "setext_with_atx"
    }
  },
  "[markdown]": {
    "editor.defaultFormatter": "yzhang.markdown-all-in-one"
  },
  "recommendations": [
    "yzhang.markdown-all-in-one"
  ]
}