📝 Default HTML `whitespaceSensitivity` breaks page layout.

[lgarron]

I'm filing this as a follow-up to #4927

I'm glad to see that Biome 2.0 stable includes an HTML formatter, but I am shocked to find that its default configuration breaks the layout of pages.

Specifically, it seems that whitespaceSensitivity is set to "ignore" by default. From my perspective, I consider this to be a severe bug.

For comparison, Biome is conservative when formatting JS files. Fixes are categorized as unsafe even if they are "obviously correct" in the vast majority of JS programs. In the same way, I think it should be a high-level goal of Biome's HTML formatter not to break:

• the parsed DOM content of the page, or
• the layout of the page.

HTML whitespace sensitivity is quirky at best, but it is well-established. I have often had to write code that relies on it, and I am certain a lot of people are maintaining projects that rely on it due to:

• code they have intentionally written this way,
• code they have written this way that accidentally relies on whitespace semantics,
• code that they are maintaining but have not written,
• snippets that were pasted because they "just work",
• etc.

If Biome ships HTML formatting with its current whitespaceSensitivity, I cannot in good conscience recommend it as a formatter. Speaking from experience, I fully expect that this will silently break projects that migrate to Biome, leading to confusion and frustration at chasing down subtle layout bugs.

As an alternative, I would like to suggest to:

• Change the default to either "css" or "strict". (I haven't yet looked into which is sufficiently safe.)
• Maybe introduce a warning to the effect of:

Biome encountered HTML that cannot be pretty-formatted without affecting the layout or parsing of the page. Consider specifying an explicit value of whitespaceSensitivity to avoid this message. For more details, consult: (link to documentation page with examples)

Environment information

CLI:
  Version:                      2.0.0
  Color support:                true

Platform:
  CPU Architecture:             aarch64
  OS:                           macos

Environment:
  BIOME_LOG_PATH:               unset
  BIOME_LOG_PREFIX_NAME:        unset
  BIOME_CONFIG_PATH:            unset
  BIOME_THREADS:                unset
  NO_COLOR:                     unset
  TERM:                         xterm-256color
  JS_RUNTIME_VERSION:           v24.2.0
  JS_RUNTIME_NAME:              node
  NODE_PACKAGE_MANAGER:         bun/1.2.15

Biome Configuration:
  Status:                       Loaded successfully
  Path:                         biome.json
  Formatter enabled:            true
  Linter enabled:               true
  Assist enabled:               true
  VCS enabled:                  true

Workspace:
  Open Documents:               0

Playground link

https://biomejs.dev/playground/?indentStyle=space&indentWidth=4&bracketSameLine=true&files.main.html=PABkAGkAdgA%2BAGEAPABzAHQAcgBvAG4AZwA%2BAGIAPAAvAHMAdAByAG8AbgBnAD4AIABjADwALwBkAGkAdgA%2BAAoAPABkAGkAdgA%2BAGEAPABkAGkAdgA%2BAGIAPAAvAGQAaQB2AD4AIABjADwALwBkAGkAdgA%2BAAoA

Code of Conduct

• I agree to follow Biome's Code of Conduct

[dyc3]

The default should be css. Note that the HTML formatter is still experimental, hence why it is disabled by default.

[lgarron]

The default should be css. Note that the HTML formatter is still experimental, hence why it is disabled by default.

Ooh, that's great to hear!

I took a look at the code, and it seems that Css is actually marked as default:

biome/crates/biome_html_formatter/src/context.rs

Lines 264 to 265 in 7cd02f2

	#[default]
	Css,

However, I don't observe this as the default functionality in Biome 2.0.0. Is that expected?

[dyc3]

Html formatting is still experimental. You are going to encounter mismatches with prettier, and problems with whitespace sensitivity as it stands right now.

We are already testing against prettier's test cases, and filing issues with specific cases like in this issue's body can help cover blind spots that might be missing from their suite.

[lgarron]

Ah, it looks like like the HTML formatter is a lot less stable than I previously thought.

For example, with both css and strict Biome breaks the semantic whitespace of the following:

<h1><a href="https://example.com/">foo</a> bar</h1>

I've also just seen it goof up up the following <style> tag:

  <style>
    #content-inner p {
      margin: 1em;
    }

    /* … */

    h2 {
      font-size: 1.25em;
    }
  </style>

… into this completely invalid syntax:

    <style
  #content-inner p {
    margin: 1em;
  }

  /* … */

  h2 {
    font-size: 1.25em;
  }
>

I have a repro for the latter, but it would take a while to extract. Let me know if it would be valuable.

[dyc3]

Oh yeah I'm definitely interested in that <style> breaking. Please file a new issue for it. :)

[lgarron]

Oh yeah I'm definitely interested in that <style> breaking. Please file a new issue for it. :)

Found it! Looks like it's specifically due to "whitespaceSensitivity": "strict"

Filed at: #6453

I wasn't able to test v2.0.3 (#6444 (comment)), but I presume it's the same issue as well.