markdownfmt makes annoying and completely unnecessary changes.

[BenKeyFSI]

markdownfmt makes annoying and completely unnecessary changes.

• ATX-style headers are converted to Setext-style headers.
• grid_tables supported by Pandoc’s Markdown are destroyed in that the required line breaks at the end of the lines are removed.

This makes markdownfmt completely unusable for most of my markdown files.

[dmitshur]

The way markdownfmt is implemented is that it parses a Markdown document (currently, using blackfriday v1) and then prints back a pretty-printed version of said markdown document.

There are multiple ways to encode the same high-level Markdown node types (headers, links). When printing back the formatted version, in blackfriday v1, the information the original style (ATX- vs Setext-style header) isn't available, so I had to make a decision about what style go with, and use it. There are some plans to try to preserve additional style variations that will be possible with blackfriday v2 (see issue #34).

When I first created markdownfmt, I wanted something like gofmt, but for Markdown files. I later realized that the reason gofmt was viable and successful is that it was an official tool that shipped with Go 1.0, so everyone had a chance to adopt it right away. Markdown didn't have this, and so there are many different styles in use, so a global tool that everyone adapts isn't possible.

It's unfortunate, but it sounds like markdownfmt won't be useful to you. But it's not possible to easily change how it works, because it goes against the goal of producing consistent and opinionated output. You can fork it and adjust it to your needs, or simply avoid using it.

[sirnewton01]

Would it be agreeable to somehow provide to markdownfmt the preferred styles for headings and other items that aren't available from the parser?

[dmitshur]

@sirnewton01 Accepting configuration is not in scope of this markdownfmt project. To customize preferred styles, I would recommend forking and either customizing the fork to your specific needs, or trying to implement accepting preferred style configuration.

[petemounce]

But it's not possible to easily change how it works, because it goes against the goal of producing consistent and opinionated output.

Would it be possible to change your opinions about the output that should be produced? Our own opinions:

• We prefer to use citation-style links because
  • they allow re-use of the same href from multiple places in the document without needing to duplicate it (and maintain those duplicates over time)
  • they allow shorter content lines - the text is easier to read, edit, and diff when raw
  • updating a link when it appears in fewer places is easier
• We prefer to use # based headers since (AFAIK and I might be ignorant) this is the most eyeball-glance friendly way of denoting the 'size' of the header (1-6) and understanding the hierarchy of the content as denoted by headers
• We prefer to limit line length to n characters (probably around 120) since this aids code-review because
  • it's easier to pinpoint a review comment if the line-comment is shorter
  • it allows review comments to be more focussed on a particular piece of content
  • it removes the case where a piece of content gets many review-comments all to the same line because it's long
  • (we wish code-review tools (hi github) allowed highlighting text to apply comments to)
  • BUT we don't now of any tools to automatically reflow when edits occur, and having that feature would be very welcome since some of us are definitely OCD ( ;) )