Docs: Show how automatic fixing works

[sils]

Would be super awesome to fix some issues automatically, say you have a duplicate heading, just remove the second.

[sils]

oh apparently you do: https://github.com/wooorm/mdast-lint#using-mdast-to-fix-your-markdown - thouh I think you could point out on how to use that feature.

[wooorm]

Certainly! mdast itself can do a lot of that (see “using mdast to fix your markdown”).

If you have some more suggestions regarding how to get that across, I’d love to hear them 😄

Not everything can be fixed (automatically), some are pretty easily done, some can be quite destructive (like the one you mentioned), especially when used in a code editor where you’re typing and fixes could happen automagically!

I’d appreciate a breakdown of these rules and how they could be fixed if you’d like to dig in 😉

[sils]

@wooorm could you provide an example command that shows how I can use mdast to autofix a file?

Background: I'm the coala developer (see the other issue :)) and we offer automatic fixing to the user but we don't do it without asking him first so destructive is ok in our case because the user has the last say.

[sils]

And IIUC you either do analysis or fixing, ideally one would be able to relate a fix to a certain issue.

[wooorm]

mdast . -o rewrites all markdown files found in the current working directory, based on sensible defaults (and settings based on configuration files). See man 1 mdast for more information.

Re coala: Yeah, I figured 😉 unist (i.e., mdast/retext/hast) definetly support automatic code fixing, however, most of hast and almost all of mdast are abstract (instead of concrete) syntax trees. Meaning, information is left out. For example, one cannot persist the type of marker used for emphasis (* v.s. _) in mdast.

IIUC

What?

Aside form that, suggesting either a setting or a plug-in to use (I prefer keeping mdast’s core small and deferring work to plug-ins) is okay with me.

[sils]

IIUC -> If I Understand Correctly

[wooorm]

👍

[wooorm]

Just getting back to this issue: Am I correct in assuming you have everything you need? Can I close this?

[sils]

This bug is not about me getting what I need (FWIW I have it :)) but about me wanting you to document this somewhere because I think it would be good.

[wooorm]

Right, in that case: I feel like everything is documented okay. As in, mdast-lint has a section regarding this linking to mdast, and mdast has an entire man page for settings packaged inside, and lists all available plug-ins.

So, IMO the stuff is there, but maybe it isn’t easily found.

Back to the Q, what information are you missing, and where would you suggest mentioning it or linking to it?

[sils]

So, IMO the stuff is there, but maybe it isn’t easily found.

I think that was my problem. Though I can't really say to you how to improve that.

[wooorm]

Okay, I hope the proposed changes in wooorm/mdast#95 will improve this.

[davidtheclark]

@wooorm: I'm confused by this situation still. As a concrete example: when I run some files through remark, I want the output list items to have one space separating - from the text, instead of 3. That's definitely a non-destructive transform. remark-preset-lint-markdown-style-guide includes a rule to enforce this. However, when I run remark with the preset as a plugin, all I get is lint warnings, not properly formatted files. In fact, remark is auto-formatting the files in a way that violates the linting. What am I doing wrong?

(Some of the links in the discussion above are now dead, so maybe I'm just not looking in the right places.)

[wooorm]

remark-lint rules only warn about stuff, other plugins may be able to fix stuff, which requires -o, --output on the CLI, or overwriting the file yourself on the API.

As remark uses an AST, lots of stuff is not available in the tree, and remark-stringify decides how to format the tree. It decides whether to use *·Item or *···Item.

If you’re using remark-stringify yourself, you can pass options in like any other plugin: .use(stringify, {listItemIndent: '1'}).

If you’re not using remark-stringify directly, e.g., with remark().use(/* ... */), you can pass options in through settings, either by passing in a preset with (just) settings: remark().use({settings: {listItemIndent: '1'}}) or setting data: remark().data({settings: {listItemIndent: '1'}}).

The docs for what stringification can be used can be found in the API section of remark-stringify.

Does that help? If you have suggestions for changed to the docs, let me know!

[davidtheclark]

@wooorm: Perfect — this is what I've been looking for. I will try to make a PR to docs that I think might clarify.

[asbjornu]

While #160 helps, I think #180 shows that an even more concrete and verbatim example is required for people (like me) to understand how to execute remark on the command line to auto-format Markdown files. I believe other command line tools such as node fmt, dotnet format and rubocop --auto-correct-all set a precedent that:

1. Fixing files according to the configured code standard is expected.
2. Fixing should be possible to do with the simple execution of a command on the terminal.

[wooorm]

The example in the readme does show the -o, --output flag? https://github.com/remarkjs/remark-lint#example-2

How could that be made clearer?

[asbjornu]

To be honest, I didn't see the mention of it since it's within a quotation block. It would be great if something like the following code example was available somewhere more prominent:

npx remark ./**/*.md --output

[solarmosaic-kflorence]

I'm also confused by this behavior. I'm using remark-cli and my .remarkrc contains:

{
  "plugins": [
    "preset-lint-markdown-style-guide",
    [ "lint-maximum-line-length", false ]
  ]
}

When I run remark path/to/some/file.md it correctly complains that my file does not conform to the style guide:

path/to/some/file.md
  5:1-5:100  warning  Marker style should be `-`                   unordered-list-marker-style  remark-lint
        5:5  warning  Incorrect list-item indent: remove 2 spaces  list-item-indent             remark-lint

However, running remark path/to/some/file.md -o writes the file out in a different format, not the format enforced by the lint style guide plugin. I'm guessing because that plugin is only used for the linting side and not the formatting side, but it's not very intuitive. Almost all formatting tools I've used essentially have a "format" and a "check" option, where "format" tries to conform to the check. How do I do that with remark?

[solarmosaic-kflorence]

Looks like #82 is possibly what I'm referring to above.