3 ms·

Related: given that markdown is meant to be read, it kind of drives me up the wall that some people nowadays run autoformatters like Prettier on it. Super-aggre

Related: given that markdown is meant to be read, it kind of drives me up the wall that some people nowadays run autoformatters like Prettier on it. Super-aggressive formatters like prettier remove various whitespace, and mangle other things that human authors do for readability. Which is fine if the file is something that's only ever meant to be parsed by scripts, but the whole point of markdown is that people read it! (edited to add: It wouldn't really be an issue if prettier had some config options for not mangling whitespace, but that ship seems to have sailed for some reason.)

diwank 2y ago
Yes! I sometimes prefer to use `====` h1s and `----` h2s especially when I am writing slides or taking notes on a live call for others and I hate that prettier and other linters would automatically turn them into `# ` and `## ` ... Please stop doing that, prettier.
The_Colonel 2y ago
Well, Markdown is a superset of HTML where extra whitespace is usually collapsed, so this behavior isn't surprising. Having "source" Markdown looking meaningfully different from the rendered Markdown seems like an anti-pattern.
- Shog9 2y ago
  As the essay and this discussion repeatedly try to emphasize, thinking of Markdown as a "superset of HTML" is missing the point - it is meant to be read. It has both meaningful and collapsible whitespace, and both allows and encourages uses of whitespace that only have a significant effect on source readability. ...Arguably, the reason HTML has collapsible whitespace is to allow writing readable source, and once upon a time it was more common to see HTML produced in a way that didn't get in the way of this (e.g. paragraphs and indentation indicated primarily via whitespace with only opening `<p>` and `<li>` tags). But that ship sailed; tooling long ago coalesced around more rigid conventions, and thus the need for Markdown emerged. Throwing those advantages away raises the question of why bother using Markdown at all.
  - The_Colonel 2y ago
    Back in 2004, Gruber introduced Markdown with this: > I’ve written a text-to-HTML formatting tool called Markdown ... which kinda suggests to me it's meant to be rendered. Markdown's major advantage is that it's (mostly) readable as plaintext (essentially a graceful degradation), but evidenced by how most tools using it render Markdown into HTML instead of showing it unrendered, it doesn't seem like people prefer reading it.
    - fenomas 2y ago
      Nobody suggested markdown isn't meant to be rendered to HTML - that's not in doubt, and it's not relevant to anything being discussed here. The people who replied to you are saying that it's nonetheless (also) meant to be read as-is -- because that's relevant to whether or not a markdown formatter should try to preserve readability, which was the topic at hand.
      - The_Colonel 2y ago
        That "also" is critical. It's primary purpose is to be rendered into HTML, but it should also be readable. Now the point is - markdown formatters only format things which won't have an effect in the rendered HTML, so why does it matter? Do you have some meaningful information encoded in markdown which does not translate to HTML? That sounds like a clear anti-pattern, since by rendering to HTML you lose it.
        fenomas 2y ago
        You're imagining that the formatter's top priority is to make markdown look similar to its rendered HTML. But that's not a goal of markdown (literally TFA), nor of Prettier, and it's not relevant too what I and some other people use markdown for. If it's relevant for you, great! This thread is me saying it ought to be configurable either way. > so why does it matter? Readability, per the whole thread.
- jpc0 2y ago
  You are confused about markdown. There is no "source markdown". Markdown is meant to be formatted to be read, without any intermediate step. "Prettifiers" like github etc are just converting the markdown into "styled" text. The format was always meant to be read as is.
  - The_Colonel 2y ago
    No, Markdown is meant to be rendered to HTML. That's why it's specified in terms of its syntax rendering to HTML. That's why inline HTML was always part of Markdown (or is the inline HTML also meant to be read without rendering?)
    - dukeyukey 2y ago
      In the words of John Gruber, the creator of markdown: > "Markdown is intended to be as easy-to-read and easy-to-write as is feasible. Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions." https://daringfireball.net/projects/markdown/syntax https://daringfireball.net/projects/markdown/syntax
      - gmfawcett 2y ago
        He can say what he wants, but he literally inlined the entirety of HTML into the syntax. It's delusional to suggest that this design choice emphasizes readability above all else.
      - The_Colonel 2y ago
        That's no contradiction to what I wrote. He says "document should be publishable", not "published". The primary publishing method remains HTML.
        dukeyukey 2y ago
        As-is, in plain text. Not HTML. It should be comfortably viewable in raw text, which precludes HTML.
- SllX 2y ago
  Markdown is an intermediate format between a writer and rendered HTML. It is easier to read, write and edit as a writer (or someone reviewing someone else’s writing intended for the web) before generating and serving HTML. It’s not a superset, it’s not a subset, and it’s not HTML, although you can include HTML tags within a Markdown document to include things Markdown does not provide coverage for. Which is to say there isn’t any such thing as “source Markdown” and “rendered Markdown”. Markdown is the source, HTML is the output, although you can make your own parser output to whatever you want.
bastawhiz 2y ago
> Which is fine if the file is something that's only ever meant to be parsed by scripts, but the whole point of markdown is that people read it! Nobody is running prettier on their code or markup for the benefit of the computer. If it's not readable, it's just a bad formatting tool (or wasn't configured properly). The whole point of a formatter is to make it easier to read.
- Shog9 2y ago
  Pretty much the only benefit I've seen of running prettier on Markdown is to highlight mistakes in formatting that otherwise wouldn't be apparent without viewing rendered output (which it highlights mostly by trashing the file in some fairly obvious way). The stated philosophy behind Prettier is to end arguments within a team about how to format code, which... Given Markdown is already heavily constrained, barely applies; unlike other languages supported by Prettier, there are precious few adjustments made to Markdown that are clearly intentionally made in pursuit of consistent readability - indeed, if I recall correctly the Prettier Markdown engine is mostly just a round-trip through the remark.js parser and stringifier, and the results reflect this - the results look mechanical, and it is just as likely to eliminate whitespace that lends clarity as it is to add it (if not, as the GP suggests, more likely). Sadly, there are remark.js plugins that could have been used to e.g. enforce consistent use of whitespace without stripping everything down to the bare minimum, but last I looked the Prettier folk were pretty hostile toward any suggestions that their (default, bare-minimum-effort) "style" was at all problematic.
- fenomas 2y ago
  Prettier disagrees, as I understand it. Its authors know it's "wrong" to take this: const matrix = [ 1, 0, 0, 0, 1, 0, 0, 0, 1, ] and collapse it onto one line. But their view is that reformatting everything from scratch is more important that such things, and that it's reasonable to add /* ignore */ comments to every single place where you want anything preserved.
danbee 2y ago
I'm not a fan of Prettier at all. A log of the time I find it makes code uglier.

diwank 2y ago

Yes! I sometimes prefer to use `====` h1s and `----` h2s especially when I am writing slides or taking notes on a live call for others and I hate that prettier and other linters would automatically turn them into `# ` and `## ` ... Please stop doing that, prettier.

The_Colonel 2y ago

Well, Markdown is a superset of HTML where extra whitespace is usually collapsed, so this behavior isn't surprising. Having "source" Markdown looking meaningfully different from the rendered Markdown seems like an anti-pattern.

Shog9 2y ago
As the essay and this discussion repeatedly try to emphasize, thinking of Markdown as a "superset of HTML" is missing the point - it is meant to be read. It has both meaningful and collapsible whitespace, and both allows and encourages uses of whitespace that only have a significant effect on source readability. ...Arguably, the reason HTML has collapsible whitespace is to allow writing readable source, and once upon a time it was more common to see HTML produced in a way that didn't get in the way of this (e.g. paragraphs and indentation indicated primarily via whitespace with only opening `<p>` and `<li>` tags). But that ship sailed; tooling long ago coalesced around more rigid conventions, and thus the need for Markdown emerged. Throwing those advantages away raises the question of why bother using Markdown at all.
- The_Colonel 2y ago
  Back in 2004, Gruber introduced Markdown with this: > I’ve written a text-to-HTML formatting tool called Markdown ... which kinda suggests to me it's meant to be rendered. Markdown's major advantage is that it's (mostly) readable as plaintext (essentially a graceful degradation), but evidenced by how most tools using it render Markdown into HTML instead of showing it unrendered, it doesn't seem like people prefer reading it.
  - fenomas 2y ago
    Nobody suggested markdown isn't meant to be rendered to HTML - that's not in doubt, and it's not relevant to anything being discussed here. The people who replied to you are saying that it's nonetheless (also) meant to be read as-is -- because that's relevant to whether or not a markdown formatter should try to preserve readability, which was the topic at hand.
    - The_Colonel 2y ago
      That "also" is critical. It's primary purpose is to be rendered into HTML, but it should also be readable. Now the point is - markdown formatters only format things which won't have an effect in the rendered HTML, so why does it matter? Do you have some meaningful information encoded in markdown which does not translate to HTML? That sounds like a clear anti-pattern, since by rendering to HTML you lose it.
      - fenomas 2y ago
        You're imagining that the formatter's top priority is to make markdown look similar to its rendered HTML. But that's not a goal of markdown (literally TFA), nor of Prettier, and it's not relevant too what I and some other people use markdown for. If it's relevant for you, great! This thread is me saying it ought to be configurable either way. > so why does it matter? Readability, per the whole thread.
jpc0 2y ago
You are confused about markdown. There is no "source markdown". Markdown is meant to be formatted to be read, without any intermediate step. "Prettifiers" like github etc are just converting the markdown into "styled" text. The format was always meant to be read as is.
- The_Colonel 2y ago
  No, Markdown is meant to be rendered to HTML. That's why it's specified in terms of its syntax rendering to HTML. That's why inline HTML was always part of Markdown (or is the inline HTML also meant to be read without rendering?)
  - dukeyukey 2y ago
    In the words of John Gruber, the creator of markdown: > "Markdown is intended to be as easy-to-read and easy-to-write as is feasible. Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions." https://daringfireball.net/projects/markdown/syntax https://daringfireball.net/projects/markdown/syntax
    - gmfawcett 2y ago
      He can say what he wants, but he literally inlined the entirety of HTML into the syntax. It's delusional to suggest that this design choice emphasizes readability above all else.
    - The_Colonel 2y ago
      That's no contradiction to what I wrote. He says "document should be publishable", not "published". The primary publishing method remains HTML.
      - dukeyukey 2y ago
        As-is, in plain text. Not HTML. It should be comfortably viewable in raw text, which precludes HTML.
SllX 2y ago
Markdown is an intermediate format between a writer and rendered HTML. It is easier to read, write and edit as a writer (or someone reviewing someone else’s writing intended for the web) before generating and serving HTML. It’s not a superset, it’s not a subset, and it’s not HTML, although you can include HTML tags within a Markdown document to include things Markdown does not provide coverage for. Which is to say there isn’t any such thing as “source Markdown” and “rendered Markdown”. Markdown is the source, HTML is the output, although you can make your own parser output to whatever you want.

bastawhiz 2y ago

> Which is fine if the file is something that's only ever meant to be parsed by scripts, but the whole point of markdown is that people read it! Nobody is running prettier on their code or markup for the benefit of the computer. If it's not readable, it's just a bad formatting tool (or wasn't configured properly). The whole point of a formatter is to make it easier to read.

Shog9 2y ago
Pretty much the only benefit I've seen of running prettier on Markdown is to highlight mistakes in formatting that otherwise wouldn't be apparent without viewing rendered output (which it highlights mostly by trashing the file in some fairly obvious way). The stated philosophy behind Prettier is to end arguments within a team about how to format code, which... Given Markdown is already heavily constrained, barely applies; unlike other languages supported by Prettier, there are precious few adjustments made to Markdown that are clearly intentionally made in pursuit of consistent readability - indeed, if I recall correctly the Prettier Markdown engine is mostly just a round-trip through the remark.js parser and stringifier, and the results reflect this - the results look mechanical, and it is just as likely to eliminate whitespace that lends clarity as it is to add it (if not, as the GP suggests, more likely). Sadly, there are remark.js plugins that could have been used to e.g. enforce consistent use of whitespace without stripping everything down to the bare minimum, but last I looked the Prettier folk were pretty hostile toward any suggestions that their (default, bare-minimum-effort) "style" was at all problematic.
fenomas 2y ago
Prettier disagrees, as I understand it. Its authors know it's "wrong" to take this: const matrix = [ 1, 0, 0, 0, 1, 0, 0, 0, 1, ] and collapse it onto one line. But their view is that reformatting everything from scratch is more important that such things, and that it's reasonable to add /* ignore */ comments to every single place where you want anything preserved.

danbee 2y ago

I'm not a fan of Prettier at all. A log of the time I find it makes code uglier.