Add Prettier Formatting for Markdown Files and Pre-Commit Hook

[MarvNC]

• Adds Prettier
• Adds .prettierconfig currently with the only rule being proseWrap: true
• Adds prettierignore set to ignore everything except markdown files
• Adds pre-commit hook

Maybe this could eventually be expanded to cover the code as well (#517 )

[github-actions]

✔️ No visual differences introduced by this PR.

View Playwright Report (note: open the "playwright-report" artifact)

[toasted-nutbread]

This may be a personal taste thing, so others feel free to chime in with any related opinions, but i think 80 character line limits (or "targets", as prettier is reporting to not be a true limit) is always way too short. Perhaps it doesn't matter since at the end of the day, Github ignores that for the most part, and maybe others feel differently. IMO if something is going to use a line limit, 120 is a bit more tolerable.

_{Unrelated: it's almost unbelievable how awful complex C++ code can look with an auto-formatter with an 80 character line limit :(}

[MarvNC]

I was considering changing that to 100 but figured defaults are generally preferred, I'd support a wider width for readmes. I find 80 width fine though for code as it prevents too much wrapping from happening when you have two editors open side to side on a small screen.

[Casheeew]

Prettier seems to do a lot of stuff that eslint stylistic can already do, which we are already using one of their plugins (stylistic/eslint-plugin-ts).
prose-wrap can be achieved by https://eslint.style/rules/js/max-len. Adding prettier means having to maintain a bunch more config files and one more github action.

Is there anything prettier can do that stylistic cant that I might not know of?

[MarvNC]

Prettier seems to do a lot of stuff that eslint stylistic can already do, which we are already using one of their plugins (stylistic/eslint-plugin-ts). prose-wrap can be achieved by https://eslint.style/rules/js/max-len. Adding prettier means having to maintain a bunch more config files and one more github action.

Is there anything prettier can do that stylistic cant that I might not know of?

I wasn't aware, but from what I understand, eslint is more intended to lint and catch issues while prettier is intended to actually make decisions about formatting. Stylistic doesn't seem to support markdown from what I'm finding.

[djahandarie]

LGTM now that the scope is just for markdown. Though needs conflict resolution. @MarvNC

[MarvNC]

LGTM now that the scope is just for markdown. Though needs conflict resolution. @MarvNC

Thanks, done. @djahandarie do you have any opinions on changing the print width?

[djahandarie]

@MarvNC Honestly, I'm against max line lengths and auto-wrapping, I think it's better for editors of files to be able to use line breaks with some semantic meaning (i.e., indicating some actual unit or separation of interest), with further concerns like overflow left to each viewer's editing environment.

[MarvNC]

@djahandarie I think it's more annoying to have no wrapping for markdown. If you choose to manually break you'll have to re-break every time you edit the text, and lengths will never be consistent and it's just more effort to break. Single line breaks have no semantic meaning after being rendered since you need a double break and I don't see much reason for giving them meaning that's only visible when viewing the raw md. Never linebreaking and relying on editor word wrap is a solution, but it's not too accessible depending on what editor you use, and word wrap can make viewing tables very annoying so I don't prefer it.

[toasted-nutbread]

Throwing another thought in here, but I don't really have a strong opinion either way, at least not until there is an obvious ugly situation in practice:

Mandatory line length limits have the potential to cause a lot of diffs when changing a small section of a larger paragraph, since it has to reorganize the entire block. The way I've generally approached markdown source is that I manually word wrap at sentence or fragment boundaries (i.e. at a period or comma), or if I feel the line gets to be unreasonably long (e.g. when embedding URLs).

If I want the raw source to word wrap, most editors have a feature to do this. For example, VSCode word wraps markdown files by default.

[djahandarie]

@MarvNC FWIW I basically 100% agree with toasted-nutbread here

[MarvNC]

My reason for wanting this is that I always format when I edit stuff, and so if I were to edit markdown there would be a bunch of unnecessary diffs (even without word wrap). I guess it's not a big deal though, and maybe not worth adding the hook to change some random * to - and enforce some indentation/line breaks in places.

[djahandarie]

My reason for wanting this is that I always format when I edit stuff, and so if I were to edit markdown there would be a bunch of unnecessary diffs (even without word wrap)

Not sure I understand... there is agreement that we want a formatter, for the exact reason you state (i.e., auto-formatting results in more consistent output and reduced diff noise). The discussion is just regarding word wrapping settings within that.

If we just disable the wrapping here, won't your editor also not wrap? Or does it forcefully wrap everything regardless of what we do in this PR?

maybe not worth adding the hook to change some random * to - and enforce some indentation/line breaks in places.

What's the downside? Seems fine to me to have it for those things.

[MarvNC]

If we just disable the wrapping here, won't your editor also not wrap? Or does it forcefully wrap everything regardless of what we do in this PR?

Sorry, I misunderstood 😅
I'll redo this branch without word wrap applied.

[MarvNC]

Okay, there should be no visible changes in the markdown files now.

...why are there conflicts, nvm