This is a project that I have been working on for several months now. I figured y’all might like a bit more insight into the tool than what I felt was appropriate for the blog post.
I mentioned that this problem is already solved by prettier. [0] Why should you use it instead of prettier?
If you are working on a Python project, you don’t have to pull in a new toolchain to reformat your Markdown files.
MarkFlow is slightly less opinionated than prettier. Lists are just updated to ensure consistent markers, not formatted to a particular one. Headings can be underlined or use `#`, the tool just makes sure your underlining is long enough. (I’m not sure if prettier can be configured to do these things.)
If you like to understand what your tools are doing, the codebase for MarkFlow is quite a bit simpler. [1]
Otherwise, prettier is by far the more mature tool. MarkFlow has been used by far fewer people.
Despite the fact that I expect most used cases to prefer prettier, I will still be actively working on MarkFlow. Those of you who have installed it or poked around the repo likely noticed that this is a 0.1.0 release. The first major release (assuming I don’t decide to lock some version of the current code into a 1.0.0) will migrate the tool from a static setup to a plugin based setup.
You may have noticed that tables are supported by MarkFlow, but they aren’t part of the standard. This is the motivation behind such a refactor where instead MarkFlow by default only works on standard CommonMark files and plugins for extensions to the standard like tables would be installed separately. This also would give people the ability to make decisions about their formatting.
Many of the reformatting tools I’ve interacted with are very opinionated. This would give users more control over the style the tool outputs. For instance, an MarkFlow-black plugin could reformat all of your Python code blocks with black. You could make sure that all bullet points use that same bullet point (this is what prettier does already).
But, why not switch to the plugin architecture before a release? I think there is still some value in the tool as it is, as noted above. In addition, I want to settle on some good defaults for MarkFlow’s output style that aren’t just from my head and hopefully get some runtime on the existing code to hammer out corner cases.
Thanks for checking out my post and sorry for the wall of text. Let me know if you have any questions or concerns.
1 comment
[ 2.7 ms ] story [ 9.5 ms ] threadThis is a project that I have been working on for several months now. I figured y’all might like a bit more insight into the tool than what I felt was appropriate for the blog post.
I mentioned that this problem is already solved by prettier. [0] Why should you use it instead of prettier? If you are working on a Python project, you don’t have to pull in a new toolchain to reformat your Markdown files. MarkFlow is slightly less opinionated than prettier. Lists are just updated to ensure consistent markers, not formatted to a particular one. Headings can be underlined or use `#`, the tool just makes sure your underlining is long enough. (I’m not sure if prettier can be configured to do these things.) If you like to understand what your tools are doing, the codebase for MarkFlow is quite a bit simpler. [1] Otherwise, prettier is by far the more mature tool. MarkFlow has been used by far fewer people.
Despite the fact that I expect most used cases to prefer prettier, I will still be actively working on MarkFlow. Those of you who have installed it or poked around the repo likely noticed that this is a 0.1.0 release. The first major release (assuming I don’t decide to lock some version of the current code into a 1.0.0) will migrate the tool from a static setup to a plugin based setup.
You may have noticed that tables are supported by MarkFlow, but they aren’t part of the standard. This is the motivation behind such a refactor where instead MarkFlow by default only works on standard CommonMark files and plugins for extensions to the standard like tables would be installed separately. This also would give people the ability to make decisions about their formatting.
Many of the reformatting tools I’ve interacted with are very opinionated. This would give users more control over the style the tool outputs. For instance, an MarkFlow-black plugin could reformat all of your Python code blocks with black. You could make sure that all bullet points use that same bullet point (this is what prettier does already).
But, why not switch to the plugin architecture before a release? I think there is still some value in the tool as it is, as noted above. In addition, I want to settle on some good defaults for MarkFlow’s output style that aren’t just from my head and hopefully get some runtime on the existing code to hammer out corner cases.
Thanks for checking out my post and sorry for the wall of text. Let me know if you have any questions or concerns.
[0] https://prettier.io/ [1] https://github.com/duo-labs/markflow/blob/main/IMPLEMENTATIO...