Use Remark beautifier for markdown files by default #2004

kachkaev · 2018-01-09T11:48:56Z

What does this implement/fix? Explain your changes.

Tidy Markdown was the first and only markdown beautifier in atom-beautify until Remark was added two years ago. As of January 2018, Remark seems to be a more promising solution for markdown according to the state of its community:

	Tidy Markdown	Remark
number of contributors	2	60
commits to master in 2017	11	50+
github stars	35	1235
downloads per months on npm	45K+	660K+

I'd like to propose switching to Remark by default and thus serve atom-beautify users with something they are more likely to be familiar with.

Does this close any currently open issues?

This may positively affect #1990 because Tidy Markdown has some issues extracting code from code blocks. If Remark is made a default choice, we can simply disable code block beautification option for Tidy Markdown without any harm to most users.

Also, if the solution to #965 is found, the default markdown beautifier will better integrate with custom markdown preferences that users may have.

Checklist

Check all those that are applicable and complete.

Merged with latest master branch
Regenerate documentation with npm run docs
Add change details to CHANGELOG.md under "Next" section
Added examples for testing to examples/ directory
Travis CI passes (Mac support)
AppVeyor passes (Windows support)

kachkaev · 2018-01-09T12:29:23Z

Tests also need updating because of slightly different default behaviours of Remark and Tidy Markdown. But WDYT in general?

stevenzeck · 2018-01-22T17:20:33Z

I'm not against this, but our remark version is really out of date (3 major versions behind). Between this, #2008 and #1990 it might be better to make it one PR since these files are all crossing one another. Also, it's preferable to use node.js for beautifiers if available so users don't have to install them separately. I would suggest looking for a global install of remark-cli first, then if there isn't one, fall back to the programmatic interface of Remark (which needs to be upgraded in atom-beautify).

kachkaev · 2018-01-26T16:35:44Z

@szeck87 so which PR would you recommend to leave as an umbrella for all these changes? I've been thinking that they deserve separate discussions and that only some suggestions will be accepted. I'll be happy to restructure my work if you recommend what to do.

kachkaev · 2018-01-26T16:40:55Z

Checking for remark-cli and falling back to a built-in remark via npm seems reasonable. Do we need any ticks in options or should I just search for node_modules/.bin/remark-cli, then remark-cli and finally require('remark-cli') on failure?

stevenzeck · 2018-01-26T17:01:06Z

@Glavin001 what's your opinion on the PR structures for #2004, #2008, and #1990?

As far as checking for global versus options, I seem to remember working on something similar and tried to use requireg, but can't remember what became of it. Is the use of remark-cli just for use of a .remarkrc file? @wooorm does node version not support the use of those files?

wooorm · 2018-01-26T17:26:06Z

@szeck87 Sorry, I’m not entirely sure what your question is?

stevenzeck · 2018-01-26T18:27:26Z

@wooorm yea sorry, let me start over. In your comment on #965, you suggested to use remark-cli instead of remark. What is the rationale there?

wooorm · 2018-01-26T18:30:04Z

remark-cli (based on unified-engine) supports file finding, config files, file ignoring, etc etc: it’s made for the file-system, and has a higher level interface.
remark (based on unified) is made for processing text, and to be used through code

stevenzeck · 2018-01-26T18:35:43Z

On second thought @kachkaev I think these can all stay as separate PRs. But I would hold off on #1990, or at least the remark specific parts of it, until #2008 is finalized.

stevenzeck · 2018-01-26T18:44:04Z

@kachkaev this PR needs a couple more things:

Can you update the link in remark.coffee to https://github.com/remarkjs/remark?
Update the examples under examples/nested-jsbeautifyrc/markdown/expected/test.md and examples/simple-jsbeautifyrc/markdown/expected/test.md and yaml-front-matter.md? The other two yaml named files are skipped so you can ignore them.

kachkaev · 2018-01-30T11:40:56Z

@szeck87 done 👍

stevenzeck

Looks good to me.

Glavin001 · 2018-02-06T00:04:58Z

examples/simple-jsbeautifyrc/markdown/expected/yaml-front-matter.md

 ---

-test ing
+ test
+   ing


It looks like Remark simply did NOT beautify this file.
Original: https://raw.githubusercontent.com/kachkaev/atom-beautify/18e7f5ebad5f83e25a6a03e05ee15ada93329328/examples/simple-jsbeautifyrc/markdown/original/yaml-front-matter.md

--- layout: default title: this is my title description: this is my description --- test ing

Yes, unfortunately remark does not format frontmatter and also does not collate the lines like in the example above. Shall we just remove this test for now?

No, this would become a regression bug for Atom-Beautify. If our users assumed continued support for YAML front-matter formatting in their Markdown files, then switching the default will completely break their usage.

I'm leaning away from switching default to Remark unless we can beautify files as least as well as we had done previous with the default (TidyMarkdown). Next release should be a clear improvement, not a bug, to users.

@wooorm do you think remark could address this anyhow with remark?

@kachkaev could you describe the possible breaking changes in the CHANGELOG? If we are going to switch from Tidy Markdown to Remark and cause all of these issues, we need to make it clear the cause and solution for users who do like their formatting looking like before.

What is “frontmatter”? Here you show YAML, but there also exists TOML and some JSON front matter format as well.

Yes, remark could support this, through plugins, something like remarkjs/ideas#3, and the linked issue contains some sample code, that should be made to format the YAML/TOML/JSON!

Glavin001 · 2018-02-06T00:08:29Z

examples/simple-jsbeautifyrc/markdown/expected/test.md

-3. three
+1.  one
+2.  two
+3.  three


Looks like it worked. However, how can a user configure this indentation? It appears to be 3 spaces for - bullets and 2 spaces for numbered bullets, such that they align for both. This looks nice, however for our current users this will cause a lot of whitespace reformatting when they beautify their Markdown files. If we could configure the default to work like it did previous that would be ideal.

Original: https://raw.githubusercontent.com/kachkaev/atom-beautify/18e7f5ebad5f83e25a6a03e05ee15ada93329328/examples/simple-jsbeautifyrc/markdown/original/test.md

# heading 1 - item - item - item ## heading 2 1. one 2. two 2. three

I think this option is listItemIndent or incrementListMarker: https://github.com/remarkjs/remark/tree/master/packages/remark-stringify#optionslistitemindent

Hmm... I'm not sure we should be switching back to old indents. Yes, the existing users may experience a one-time problem after an update, but that's expected given that the formatter being used is now different. Anyone can switch back to Tidy Markdown and thus restore the original behaviour.

Four characters per intent is a very reasonable choice and sticking to this rule has more benefits in the long run. In any case, it's not the only breaking change that people might see.

In light of the lack of YAML font-matter support and these indentation changes, we need to make sure the CHANGELOG describes all of the breaking changes made by switching to Remark. Also, I would like to have more examples/tests added for Markdown showcasing the value and expected result from switching to Remark.

Glavin001 · 2018-02-06T00:08:54Z

src/languages/markdown.coffee

@@ -18,7 +18,7 @@ module.exports = {
    "md"
  ]

-  defaultBeautifier: "Tidy Markdown"
+  defaultBeautifier: "Remark"


I think you make a good argument for defaulting to Remark 👍 . However, first need to address the changes in expected above.

Glavin001 · 2018-02-06T00:10:08Z

Thank you for this Pull Request, @kachkaev! Great work so far. Close to merging 😄 .

Glavin001 · 2018-02-06T00:14:04Z

src/beautifiers/remark.coffee

@@ -3,7 +3,7 @@ Beautifier = require('./beautifier')

 module.exports = class Remark extends Beautifier
  name: "Remark"
-  link: "https://github.com/wooorm/remark"
+  link: "https://github.com/remarkjs/remark"


Options are listed: https://github.com/remarkjs/remark/tree/master/packages/remark-stringify#options

kachkaev · 2018-02-06T16:10:52Z

Thanks for your feedback @Glavin001! I tried to address the questions you've raised and am happy to hear what you think again!

kachkaev · 2018-02-06T16:26:55Z

CI fails, but according to the logs, the problem is with examples/simple-jsbeautifyrc/tsx/expected/test.tsx, not markdown files 🤔

kachkaev · 2018-02-08T17:49:30Z

Hmm... After checking out markdown formatting with prettier in the last couple of days, I'm in doubt that we should switch from 2/3 space indents to a fixed indent of four. Prettier also uses remark, but it's only for parsing. The details on how they generate the output is in this feature PR: prettier/prettier#2943. There've been some changes since then, e.g. the use of * instead of - in unordered lists.

So what shall we do with list item spacing? 🤔

Glavin001 · 2018-03-02T02:40:29Z

Thank you for contributing and your great work, @kachkaev !!

Glavin001 · 2018-03-02T04:47:19Z

Published to v0.32.0

kachkaev added 3 commits January 9, 2018 14:12

Use Remark beautifier for markdown files by default

52933a8

Update docs

d0918e9

Add CHANGELOG item

d6ee1cf

kachkaev mentioned this pull request Jan 11, 2018

Switch to remark-cli to support .remarkrc and unlock remark version #2008

Closed

6 tasks

kachkaev added 2 commits January 30, 2018 11:37

Update markdown tests

0525c05

Update link to remark repo

18e7f5e

stevenzeck requested review from Glavin001 and stevenzeck January 30, 2018 16:44

stevenzeck approved these changes Jan 30, 2018

View reviewed changes

Glavin001 self-assigned this Feb 6, 2018

Glavin001 requested changes Feb 6, 2018

View reviewed changes

Glavin001 reviewed Feb 6, 2018

View reviewed changes

Glavin001 added enhancement high priority labels Feb 6, 2018

Merge branch 'master' into remark-by-default

1163b93

Glavin001 assigned kachkaev and unassigned Glavin001 Feb 6, 2018

Add tests for custom Remark options in .jsbeautifyrc

74efe30

Describe breaking changes in CHANGELOG

b8fa552

kachkaev mentioned this pull request Feb 13, 2018

Elm-format as prettier plugin? avh4/elm-format#459

Closed

kachkaev mentioned this pull request Feb 21, 2018

Add prettier beautifier and bracket_spacing option #2047

Merged

6 tasks

Glavin001 approved these changes Mar 2, 2018

View reviewed changes

Glavin001 merged commit b8fa552 into Glavin001:master Mar 2, 2018

Glavin001 added the pending-publication label Mar 2, 2018

Glavin001 added published and removed pending-publication labels Mar 2, 2018

Glavin001 added this to the v0.32.0 milestone Mar 2, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use Remark beautifier for markdown files by default #2004

Use Remark beautifier for markdown files by default #2004

kachkaev commented Jan 9, 2018 •

edited

kachkaev commented Jan 9, 2018 •

edited

stevenzeck commented Jan 22, 2018

kachkaev commented Jan 26, 2018 •

edited

kachkaev commented Jan 26, 2018 •

edited

stevenzeck commented Jan 26, 2018

wooorm commented Jan 26, 2018

stevenzeck commented Jan 26, 2018

wooorm commented Jan 26, 2018

stevenzeck commented Jan 26, 2018

stevenzeck commented Jan 26, 2018

kachkaev commented Jan 30, 2018

stevenzeck left a comment

Glavin001 Feb 6, 2018

kachkaev Feb 6, 2018

Glavin001 Feb 6, 2018

kachkaev Feb 6, 2018 •

edited

Glavin001 Feb 6, 2018

wooorm Feb 6, 2018

Glavin001 Feb 6, 2018

Glavin001 Feb 6, 2018

kachkaev Feb 6, 2018

Glavin001 Feb 6, 2018

Glavin001 Feb 6, 2018

Glavin001 commented Feb 6, 2018

Glavin001 Feb 6, 2018

kachkaev commented Feb 6, 2018

kachkaev commented Feb 6, 2018

kachkaev commented Feb 8, 2018 •

edited

Glavin001 commented Mar 2, 2018

Glavin001 commented Mar 2, 2018

-. three
+.  one
+.  two
+.  three

Use Remark beautifier for markdown files by default #2004

Use Remark beautifier for markdown files by default #2004

Conversation

kachkaev commented Jan 9, 2018 • edited

What does this implement/fix? Explain your changes.

Does this close any currently open issues?

Checklist

kachkaev commented Jan 9, 2018 • edited

stevenzeck commented Jan 22, 2018

kachkaev commented Jan 26, 2018 • edited

kachkaev commented Jan 26, 2018 • edited

stevenzeck commented Jan 26, 2018

wooorm commented Jan 26, 2018

stevenzeck commented Jan 26, 2018

wooorm commented Jan 26, 2018

stevenzeck commented Jan 26, 2018

stevenzeck commented Jan 26, 2018

kachkaev commented Jan 30, 2018

stevenzeck left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kachkaev Feb 6, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Glavin001 commented Feb 6, 2018

Choose a reason for hiding this comment

kachkaev commented Feb 6, 2018

kachkaev commented Feb 6, 2018

kachkaev commented Feb 8, 2018 • edited

Glavin001 commented Mar 2, 2018

Glavin001 commented Mar 2, 2018

kachkaev commented Jan 9, 2018 •

edited

kachkaev commented Jan 9, 2018 •

edited

kachkaev commented Jan 26, 2018 •

edited

kachkaev commented Jan 26, 2018 •

edited

kachkaev Feb 6, 2018 •

edited

kachkaev commented Feb 8, 2018 •

edited