Prettier and closing slashes in HTML

[wbamberg]

We're starting to use Prettier to format code samples on MDN, and one issue in particular has come up.

Prettier wants to add closing slashes to empty HTML elements:

<input type="text" />

...rather than:

<input type="text">

This was in conflict with our coding guidelines, which have since been updated (mdn/content#20528).

It seems that many people do not like this Prettier behavior:

• Reduce “HTML attribute: required” example to conforming HTML markup content#21036
• HTML code style: No trailing slash, add note about prettier content#20528 (comment)
• Add an option to prefer void tags over self closing tags. prettier/prettier#5246

It's not that clear what the best option here is though. Options include:

1. fork Prettier to change its behavior: this has been suggested already to enable us to use a generic no-lint keyword on code blocks, rather than js-nolint, etc
2. stop using Prettier only on HTML code blocks. This is not that easy to do AFAIK, again because Prettier is not very configurable.
3. use something else that is more configurable, instead of Prettier

---

(Edited: "noone likes"->"many people do not like")

[wbamberg]

I think one thing that worries me is: perhaps the use case for doc samples is different from that for production code. For production code, you can just write the code any way you like and the formatter will make everything consistent. In a way, the choice doesn't matter much (see https://dev.to/michaeljota/i-changed-my-opinion-about-prettier-not-formatting-void-elements-as-is-and-this-is-why-50hk). But code samples are designed to be read not written, so maybe these formatting choices are more important for us.

[rubiesonthesky]

There is option to fork Prettier and include the changes that would be beneficial if it comes to it. I already tried this and was able to add some features that could be useful:

• no-format meta tag with embed code blocks. This will tell prettier that it should not format the code block at all. Example:

```html no-format
<input type="text">
```

• Option useVoidTags which will not add trailing slashes to html and will remove existing ones. Someone already did the work in this PR [DO NOT MERGE] Do not add / to HTML void tags prettier/prettier#8628 :) (that PR does not add option for it, it just removes all trailing slashes)

So, it's easy to create fork and implement these changes for Prettier. However, forking Prettier would mean that someone needs to host and maintain the fork and keep it up-to-date. :)

[rubiesonthesky]

stop using Prettier only on HTML code blocks. This is not that easy to do AFAIK, again because Prettier is not very configurable.

This is AFAIK possible. You can only override Prettier based on file name, but you can't say that "don't format any html". This would also need forking. :(

[Josh-Cena]

It seems no-one likes this Prettier behavior:

This is just self-selection bias. In the last meeting, I think we re-affirmed consensus that editors find trailing slashes more readable.

[wbamberg]

OK, I have updated this. I think it is still the case that many people have expressed a preference for the other option, including people who weren't in the meeting but still have a legitimate interest.

[Josh-Cena]

Can't speak for anyone else but I do find trailing slashes more readable. It doesn't break anything and is standardized. Can't see any reason for omitting it, apart from maybe that it's two fewer characters to type. Maybe we can say "we don't care" and fork Prettier so that it's ignored, but establishing the opposite preference seems odd.

[hsivonen]

I think the following points are relevant:

• As a matter of history, the HTML spec permitted the slash very reluctantly in order to make polyglot / Appendix C syntax into a non-error. The slash most certainly wasn't endorsed or meant to be added. Instead, the spec stopped asking people to remove it. (I took part in the standardization discussion at the time.)
• The slash doesn't actually close a void element. Having it in all examples suggests that it's somehow important, which gives readers the wrong idea of how HTML works. The way HTML works is that there's a set of void elements that people who write HTML just have to know are special. Having something in examples that is suggestive of actually being what closes the element when in truth the element name is hard-coded into the parser is pedagogically bad for the purpose of making the reader understand how stuff works. (As an implementor of an HTML parser in a browser, I think it's bad when people have the wrong mental model of how this stuff works.)
• The slash interacts badly with another HTML syntax feature: unquoted attribute values. (A slash before the > that ends the tag becomes part of the last attribute value if that attribute value is unquoted and there isn't a space in between.) When HTML markup is produced programmatically as is the case when Prettier rewrites HTML, unquoted attribute values are useless. It's always correct to use quotes. However, when writing HTML by hand without an editor that autogenerates quotes, unquoted attributes are a convenient feature. This means that we have a convenient feature (unquoted attribute values) that interacts badly with a feature that literally has no effect (trailing slash on void elements). I think in a case like this, teaching materials shouldn't teach something that has no effect but is a hazard when used together with a feature that has some positive convenience.
• While a space before the slash is necessary if the slash follows an unquoted attribute value, Prettier puts a space before the slash even when there are no attributes or when the last attribute value is quoted (as all Prettier-written attribute values are). This space is technically unnecessary in the post-Netscape 4 world. While one could post-hoc rationalize the space as a stylistic preference, its origin is in making pre-Gecko Netscape tolerate Appendix C markup. This gives the code smell of perpetuating old practices when they have become obsolete, which is a bad look for a teaching resource that is supposed to be up-to-date.
• People and even popular tools are very, very confused about the slash. For example, VS Code highlights the slash as if it wasn't part of an unquoted attribute value even though it objectively is part of the attribute value per spec. It's just better to steer clear of the slash.

I think Prettier is, therefore, unsuited for teaching materials and, if Prettier won't budge, I think MDN (or other teaching materials) either shouldn't use Prettier or should use a version with the trailing slash on void elements patched out.

[Josh-Cena]

Well said. I don't have strong opinions on this (although mild preference towards with-trailing-slash), but let me try responding to some of the points here.

permitted the slash very reluctantly

I've heard a few times how hard the decision was for the HTML spec editors to allow this, but IMO the spec authors' opinion is immaterial—what's more important is which one better serves the developers. The fact that this still gets pushed through proves that there's a strong force in the community in favor of trailing slashes. If it does get standardized, developers should be entitled to use it.

The slash doesn't actually close a void element.

There are many language constructs that are actually cosmetic despite looking syntactic. Think about trailing commas in JavaScript. Let's not talk in terms of parsers—humans are not parsers that consume HTML as token streams. When we see a <img src="foo" alt="bar"> tag—at least for me—I would lookahead a few tags to find where it ends (this is especially the case if the markup is not properly indented) and end up realizing that <img> is a void element. Adding a slash is an explicit indicator that the tag ends right here and eases the developer's mental burden. I don't want to memorize the syntactic trivia of which elements are void. (Of course, there are other kinds of syntactic trivia that're kind of forced on me, like Prettier's parser would literally choke on <p><pre>a</pre></p>)

This is even more confusing when mixed with implied end tags. As another contrived example, imagine a new learner thinking that <meta> behaves like <p>. They would write <head><meta>Some description about my site<meta>Some other information</head>. Of course that's broken, but Prettier will make it immediately apparent that the tag does not end where they believe it would.

unquoted attribute values

Generally, this is a point taken. Just want to point out that if you assume a developer is confident enough to write unquoted attributes, you may also reasonably assume they know that trailing slashes are cosmetic, since in our HTML learning doc, we clearly pointed out that the trailing slash is optional but kind of hinted that the quotes are mandatory:

An attribute value, wrapped with opening and closing quote marks.

...while I don't know if there's a more comprehensive HTML syntax reference.

I noticed the next two points both seem to build on unquoted attribute values somehow, but I want to point out that people who do that are probably a much smaller minority compared to people who either add or omit the trailing slash. It's a strawman to say "doing X makes their lives better", because doing X or not, most people are not going to write unquoted attributes anyway.

(Maybe I come with my bias, but I believe in 2022, web developers can no longer get away with hand-writing HTML in a plain text editor and teleporting it directly to an HTTP server, without any bundling/minifying anyway. Some sort of tooling is always necessary, and auto-quoting attributes seems to be the lowest of all bars.)

a space before the slash

This is purely stylistic. I find the space more appealing and makes the tag visually balanced. But that's just me who has been using Prettier for quite a while. We will definitely let Prettier make the spacing decisions, even if we want it to shut up on slashes.

VS Code highlights the slash as if it wasn't part of an unquoted attribute value

VS Code gets easily confused by a lot of things and its tmLanguage setup leaves a lot to be desired. For example, it will mark foo in

const templates = (
  await fs.readdir("path-to-template-directory")
).filter((name) => !excludePattern.test(name));

...as a function, because it can only analyze single lines. That doesn't mean we shouldn't format the code like the way above. If using Prettier to steer our style guide is tail wagging the dog, then so is using VS Code to tell us how code should be formatted—especially since it's not even their decision, it's simply a bug.

Unquoted attributes aside, What are the benefits of using trailing slashes?

• Less mental burden, as I talked about above. Polyglot is a big factor. Even if you always write HTML, you will find yourself writing embedded SVG and MathML where XML rules. You don't want to be switching styles every time.
• Better compatibility with JSX. JSX is designed such that you can copy/paste HTML and likely end up with valid code. (They even have some weird HTML entity rules encoded in the syntax to make sure that's the case.) I write 10x more JSX these days than HTML and I enjoy cross-pasting code and making it work everywhere. If you are a React developer and you want to readily benefit from the MDN code examples, us keeping the trailing slash will make your life much easier.
• Conforming to industry standards. At least in the JS world, Prettier is the de facto formatting standard. I believe those who care about code quality enough (which may imply they don't use unquoted attributes either? :D) would also apply Prettier to HTML. We are better off adhering to some established standard (yes, think about Prettier as a standard in itself rather than a kitchen-sink formatter) that's likely wide-adopted than straw-manning a standard ourselves.
• More of a defensive point but I do want to point out that—again, unquoted attributes aside—trailing slashes have never broken any site in more than a decade, so even if we reverted our style guide change, our argument against trailing slashes is super weak, and there's virtually no pragmatic reason why a developer (who care more about DX than what the standard body thinks) should avoid them.

[hsivonen]

Less mental burden, as I talked about above.

I think this is a key point of differing view. I think it's actively harmful in teaching material to give people the idea that one should take /> as a self-closing indication instead of learning to read img, br, etc. as not having an end tag. The notion that one should look for /> is a simpler reading rule, but it's also wrong: <div/> isn't self-closing and <img> doesn't collect subsequent text as its child.

Looking for /> works as a human reading rule in an environment where everything that one might read has gone through a tool like Prettier. I think MDN should teach readers to understand how HTML itself works generally instead of preparing readers only to work in a particular kind of controlled environment.

Better compatibility with JSX.

It's unfortunate that an HTML-lookalike, yet different, syntax has broad enough use to mess with how people understand HTML itself.

Conforming to industry standards.

Before this change, MDN as an "industry standard" counseled otherwise. Google's style guide still does. Moreover, I think industry popularity of Prettier is irrelevant to the point I'm making about teaching materials giving people the wrong mental model of how HTML works. Whether something is OK as output of an automated tool does not automatically mean that the same thing is good to show on teaching material when readers aren't guaranteed to post-process what they write and aren't guaranteed to work in environments where they only read preprocessed HTML and don't encounter the full range of the language.

The core of my argument isn't that one or the other is a more industry-standard way to write. The core of my argument is that it's harmful for teaching materials to give people the wrong mental model of how HTML works, and the slashes are more likely to teach the wrong mental model and the lack of slashes is more likely to teach the correct mental model.

trailing slashes have never broken any site in more than a decade

Trailing slashes on void elements aren't what's causing brokenness. Failure to learn the correct mental model, which involves knowing that HTML, for better or worse, has a hard-coded list of "void elements", causes breakage when someone writes e.g. <div/> based on the incorrect mental model.

I think teaching materials about HTML should not, as a side effect of stylistic choices or otherwise, obscure the fact that there is a special list of void elements that one cannot ignore and the /> syntax (when the slash is not part of an unquoted attribute value) has no effect.

[teoli2003]

I have no strong feelings here. Nevertheless:

I'm curious to know the advantages and disadvantages of both solutions, adding slashes or not adding slashes. Like Adding slashes makes the code XML compatible, or Not making them write the code easier to write, … This would allow us to know the best solution for our readership, decoupling this problem from the "How do you reach this ideal solution" question.

[hsivonen]

XML-compatibility is an illusory advantage in the vast majority of cases. That was all argued 20 years ago, and the empirical result was that if you aren't working with XML tools, the probability that you introduce syntax that's rejected as XML is so high that serendipitous XML parsing won't work. Also, HTML parsers are readily available, so the meme from 20 years ago that XML parsers are available but HTML parsers are not is no longer relevant (hasn't been for over a decade).

[RobBelics]

Let's read what the W3C people who maintain the HTML validator have to say about this:

Trailing slashes in void-element start tags do not mark the start tags as self-closing. The whole page is a good read.

[SamuelMarks]

Yep exactly mdn/content#22508

[hsivonen]

What are the next steps on this topic?

[estelle]

The google style guides are almost an antithesis of what we are teaching at MDN. But Google doesn't hire n00bs; so their target market is not ours. On the contrary.

As someone who teaches new-to-dev people all the time, the /> is super helpful. Some internal “best practices”, like the one for Google devs, tell developers not to close out any tags that don’t need to be closed out; such as </li> and </p>. N00bs don’t know which to close and which not to close, so starting with “close them all” I find is the best teaching method.

The mishmash of what is seen on viewsource, between self-closing, closing all, closing only the required, and closing only those that would actually break prod makes “view source” not a good teacher in this area. I recommend “erring” on showing examples showing the strictest method, and allowing people to slack as they learn, rather than showing the opposite.

The google recommends committing optional tags, like <HTML>; we not only recommend it, but include it in every example that includes the header, and has the lang attribute there. (we also include meta charset and viewport meta; another reason the google doc is NOT relevant to MDN documentation)

So, yeah, as someone who focuses on teaching new-to-dev people HTML, I always close empty elements, always include optional closing tags, and always include optional tags. Best practices for teaching are not the same as "reduce every single byte possible" best practices.

[hsivonen]

As someone who teaches new-to-dev people all the time, the /> is super helpful.

What do you teach people about where they can and can't put the /> ?

[RobBelics]

We shouldn't be having this discussion as we should resolve to keep them.

You can't resolve to keep something that never existed. No HTML specification has ever required a closing slash and, from a link I provided earlier, it does not mark a tag as self closing.

Guiding people to close all their tags as they learn is indeed the best way to teach HTML to newcomers.

Self closing tags are closed and do not need a slash to close them. Guiding people to put a slash there can only confuse those who read the specification and do not see anywhere that it is mentioned or used or required.

[estelle]

https://www.w3.org/TR/xhtml1/#h-4.6

[RobBelics]

This discussion is about HTML, not XML or XHTML.

[hsivonen]

https://www.w3.org/TR/xhtml1/#h-4.6 has been superseded by https://html.spec.whatwg.org/ , so https://www.w3.org/TR/xhtml1/#h-4.6 isn't really a good basis for teaching these days.

I asked what you teach people about where they can and can't put the /> , because it seems to me that teaching that requires teaching the void element list, which might as well be taught as "you don't use an end tag for these elements" without mixing /> to it.

[schalkneethling]

This discussion has turned into quite a topic. Some people have strong feelings about this and wish to encourage debate, while others want a conclusion above all. There are a couple of items to address. The first is forking Prettier to make the changes needed to adopt this change regarding self-closing tags and possibly even broader optional use of the forward slash in HTML.

The MDN Web Docs team has decided not to fork Prettier as it will introduce a big maintenance burden that is not sustainable. Anyone is, of course, welcome to take this conversation to the Prettier projects, but we would like you to keep the following in mind:
Prettier is not adopting this because of the complexity it will add to how and when it applies this rule. Prettier will have to determine the context it is running in to use this rule only in pure HTML. One might think that looking at the file extension will be enough of a hint, but this is only sometimes the case.

There are more and more places where you can use JSX, and the file extension only sometimes clarifies this. Even in projects such as React, authors only occasionally use the.jsx extension for files that uses JSX. There is also a problem with formatting code blocks with no file extension.

Here, annotating your code fences can help, but Prettier must rely on the author. Finally, there is a backward compatibility problem. That is a long way of saying that we understand why this is no simple thing for Prettier to adopt.
So, for now, we will stick with Prettier and keep an eye on the developments around this topic.

Ultimately, these changes must be evangelized with authors and educators using a slow and methodical approach. With this in mind, we propose to review the Learn section and update it with clear guidance on the elements in question.