-
We should be running Prettier on our Markdown files to ensure that they are, well, pretty. I'm not very familiar with good practices here so I'm happy to get guidance. But to get things started, here is my understanding. The h2m converter we use is already running Prettier, so what we start out with should be formatted properly. What we want is to ensure that it stays formatted properly without editors having to do this manually. I think the approach is something like:
That way editors can write Markdown any way they like, and when they commit their changes are automatically reformatted. Assuming that's the general approach, there are a couple of complexities: Prettier configurationFirst is Prettier configuration. I think there are two options we care about here: Prose wrapWe want Embedded language formattingThis is a tricky one. We found that prettifying embedded HTML broke things (prettier/prettier#10950, mdn/content#5193 (comment)). So Gregor disabled it for everything except tables. Meaning that in the converter we pass So it seems like the best thing would be to disable I just experimented using my editor's Prettier plugin, and it does format code blocks but doesn't format embedded HTML, which seems to be what we would like. But I don't know if it would work the same using the Prettier CLI. markdown-lintWe would also like to run markdown-lint on our source. I guess the general approach would be the same (pre-commit hooks). But we would need to disable any rules that conflict with Prettier. |
Beta Was this translation helpful? Give feedback.
Replies: 5 comments 3 replies
-
Overall approach
I think this approach will only be part of the story. I expect a lot of contributions to come through GitHub's web editor, where commit hooks won't happen (perhaps a lot more contributions, even, once we're in Markdown and editing becomes easier). Also, curmudgeons like me who come with their own byzantine Git habits will bypass Husky, too. I'd prefer for hooks to be opt-in rather than opt-out, to be honest; my experience with Husky has always been slow and distracting. Instead, I think we'll probably want a couple different tools to help apply formatting consistently:
Formatting code blocks
I wonder if we could override embedded languages selectively? Perhaps we could sub in no-op parser for HTML only. Rooting around in the Prettier issues, it looks like some projects have done something like this (prettier/prettier#5919 has some interesting discussion here; seems that WordPress has done a minor fork of Prettier, which may be inspirational). |
Beta Was this translation helpful? Give feedback.
-
I'd be OK with pretiffying being done in CI provided we trusted it only happen on the final merge into main. If not done in the final step, my preference would be that prettify is something I do in yari OR I can trigger in the PR. CI could still report the need to run prettifier, but at least I would choose when this happens and it wouldn't conflict with a normal editorial workflow. |
Beta Was this translation helpful? Give feedback.
-
FYI, I'd suggest https://www.npmjs.com/package/lint-staged over plain Husky, since then the linter (prettier, Markdownlint, yari, etc...) only executes on the changed files, instead of a slower crawl on everything. The big husky hooks are usually when I start to skip them like @ddbeck |
Beta Was this translation helpful? Give feedback.
-
If we don’t want to burden the contributors(online GitHub) then is it possible to implement following things?
|
Beta Was this translation helpful? Give feedback.
-
I think we can mark this as done given all of the work that has been completed on this. Here are some highlights:
Well done, everybody! |
Beta Was this translation helpful? Give feedback.
I think we can mark this as done given all of the work that has been completed on this.
Here are some highlights:
Well done, everybody!