Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

tools: add remark-lint configuration in .remarkrc #7729

Merged
merged 2 commits into from
Aug 7, 2016

Conversation

ChALkeR
Copy link
Member

@ChALkeR ChALkeR commented Jul 14, 2016

Checklist
  • commit message follows commit guidelines
Affected core subsystem(s)

tools, doc

Description of change

Specifies the configuration for remark-lint, a markdown linter.

This configuration will not cause any warnings on any of the currently present *.md files (ignoring thirdparty), once #7727 lands (hence blocked now).

It is useful not only for possible future tooling that would check the markdown files syntax, but also as a configuration for editor plugins, e.g. linter-markdown for atom-linter.

Issues fixed in #7637 and #7727 were mostly found using remark-lint.

/cc @nodejs/documentation @addaleax @silverwind @mscdex @Fishrock123.

@ChALkeR ChALkeR added doc Issues and PRs related to the documentations. tools Issues and PRs related to the tools directory. blocked PRs that are blocked by other issues or PRs. labels Jul 14, 2016
@ChALkeR
Copy link
Member Author

ChALkeR commented Jul 14, 2016

Once this lands, I will propose remark-cli + remark-lint tooling for linting our *.md files similar to how *.js files are linted with eslint.

That should prevent future errors like the ones fixed in #7637 (that fixed several actual errors that broke something in the docs, not just formatting issues) and #7590.

@cjihrig
Copy link
Contributor

cjihrig commented Jul 14, 2016

Mostly a rubber stamp LGTM. Linting the docs is a great idea.

@targos
Copy link
Member

targos commented Jul 14, 2016

👍

Is it capable of finding errors in the relative links (especially in the fragment identifiers)? That would be awesome.

@silverwind
Copy link
Contributor

Is it capable of finding errors in the relative links

That'd be glorious indeed.

@addaleax
Copy link
Member

Is it capable of finding errors in the relative links

I doubt it, the doctool generates its own non-standard format for the anchors (I think that’s done so that there are no duplicates in the generated all.html).

I’ve been occasionally using my own tooling for that, but it needs to be applied to the generated HTML docs instead of the source.

@eljefedelrodeodeljefe
Copy link
Contributor

eljefedelrodeodeljefe commented Jul 15, 2016

I think this file shoudn't need to be top-level for a couple of reasons.

  1. remark is not included as dependency
  2. we were considering building own doc tooling (missing reference to @addaleax issue), and would have based it on remark. Linting could be part of it, but hardly as third party format.
  3. the file is nonessential to building and maintaining node and hence should rather be in tooling, not to confuse newcomers
  4. remark can, in a couple of years, be exactly what marked is now: an unmaintained npm library, that should leave vendored baggage around.

Sorry, strong -1 in this form. But the intention should be picked up for sure.

@addaleax
Copy link
Member

@eljefedelrodeodeljefe Would you think differently about this if remark was, in fact, included as a dependency and/or became the underlying markdown parser for the doctool?

@eljefedelrodeodeljefe
Copy link
Contributor

yes.

@ChALkeR
Copy link
Member Author

ChALkeR commented Jul 15, 2016

@eljefedelrodeodeljefe, this is valuable even without proper tooling on our side (though I plan to add such tooling, just wanted to keep things separate) — code editors (e.g. Atom with linter-markdown plugin) read that file and use that to highlight formatting issues in markdown files. Note that we have .editorconfig in place and I haven't seen it confusing anyone. This sets a project-level config, putting it inside the tooling dir would break editor plugins integration. That config is also specific to our markdown files, hence it doesn't belong in the user configuration.

Nevertheless, I will probably file a pull request with actual remark-cli and remark-lint inclusion around tomorrow.

@eljefedelrodeodeljefe
Copy link
Contributor

hmm. Valid point - some at least.

Maybe just hold off on that until we have done actual work on proper tooling and we integrate that right away. That would decrease module bloat at least and we wouldn't continue with the patch work.

addaleax added a commit to addaleax/node that referenced this pull request Jul 15, 2016
Use blockquotes instead of code blocks for stability markers in
the docs. Doing that:

- Makes the makers appear correctly when viewed e.g. on github.
- Allows remark-lint rules like `no-undefined-references` to work
  properly (nodejs#7729).
addaleax added a commit to addaleax/node that referenced this pull request Aug 3, 2016
Use blockquotes instead of code blocks for stability markers in
the docs. Doing that:

- Makes the makers appear correctly when viewed e.g. on github.
- Allows remark-lint rules like `no-undefined-references` to work
  properly (nodejs#7729).
@ChALkeR
Copy link
Member Author

ChALkeR commented Aug 4, 2016

/cc @Trott

@Trott
Copy link
Member

Trott commented Aug 4, 2016

LGTM

@ChALkeR
Copy link
Member Author

ChALkeR commented Aug 4, 2016

This should be good to land once #7971 and #7727 are landed.

We can then fix the code blocks language specifications and remove the "no-shell-dollars": false, exception.

no-unused-definitions should be fixed by #7757.

@jasnell
Copy link
Member

jasnell commented Aug 4, 2016

Rubber stamp LGTM

addaleax added a commit that referenced this pull request Aug 4, 2016
Use blockquotes instead of code blocks for stability markers in
the docs. Doing that:

- Makes the makers appear correctly when viewed e.g. on github.
- Allows remark-lint rules like `no-undefined-references` to work
  properly (#7729).

PR-URL: #7757
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Сковорода Никита Андреевич <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
@ChALkeR ChALkeR removed the blocked PRs that are blocked by other issues or PRs. label Aug 5, 2016
@ChALkeR ChALkeR force-pushed the remark-config branch 2 times, most recently from 6de0414 to c4d7271 Compare August 5, 2016 21:29
@ChALkeR
Copy link
Member Author

ChALkeR commented Aug 5, 2016

Yay, I removed the no-unused-definitions exception due to @addaleax awesome work in #7757.

I have added one more commit because another error made it to the docs while this was here, could someone review that one too? Should be trivial. /cc @nodejs/collaborators

@eljefedelrodeodeljefe I still don't see the reason to hold this util the tooling is ready, this at least defines some rules that could help to find errors in the docs.

Going to land this if no objections.

@ChALkeR
Copy link
Member Author

ChALkeR commented Aug 7, 2016

Thanks, all! Landed in b779eb4...4c86fa3.

@ChALkeR ChALkeR deleted the remark-config branch August 7, 2016 07:50
@cjihrig cjihrig mentioned this pull request Aug 8, 2016
cjihrig pushed a commit that referenced this pull request Aug 10, 2016
Use blockquotes instead of code blocks for stability markers in
the docs. Doing that:

- Makes the makers appear correctly when viewed e.g. on github.
- Allows remark-lint rules like `no-undefined-references` to work
  properly (#7729).

PR-URL: #7757
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Сковорода Никита Андреевич <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>

Conflicts:
	doc/api/punycode.md
cjihrig pushed a commit that referenced this pull request Aug 10, 2016
Specifies the configuration for remark-lint, a markdown linter.

This configuration does not cause any warnings on any of the currently
present *.md files (ignoring thirdparty).

It is useful not only for possible future tooling that would check the
markdown files syntax, but also as a configuration for editor plugins,
e.g. linter-markdown for atom-linter.

Refs: #7637
Refs: #7727
Refs: #7757
PR-URL: #7729
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Rich Trott <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Robert Jefe Lindstaedt <[email protected]>
cjihrig pushed a commit that referenced this pull request Aug 10, 2016
This fixes a markdown formatting error in 2016-07-13 CTC meeting
minutes, __proto__ was rendered incorrectly.

This was found by remark-lint.

PR-URL: #7729
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Robert Jefe Lindstaedt <[email protected]>
@cjihrig cjihrig mentioned this pull request Aug 11, 2016
MylesBorins pushed a commit that referenced this pull request Sep 9, 2016
Specifies the configuration for remark-lint, a markdown linter.

This configuration does not cause any warnings on any of the currently
present *.md files (ignoring thirdparty).

It is useful not only for possible future tooling that would check the
markdown files syntax, but also as a configuration for editor plugins,
e.g. linter-markdown for atom-linter.

Refs: #7637
Refs: #7727
Refs: #7757
PR-URL: #7729
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Rich Trott <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Robert Jefe Lindstaedt <[email protected]>
MylesBorins pushed a commit that referenced this pull request Sep 9, 2016
This fixes a markdown formatting error in 2016-07-13 CTC meeting
minutes, __proto__ was rendered incorrectly.

This was found by remark-lint.

PR-URL: #7729
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Robert Jefe Lindstaedt <[email protected]>
MylesBorins pushed a commit that referenced this pull request Sep 28, 2016
Specifies the configuration for remark-lint, a markdown linter.

This configuration does not cause any warnings on any of the currently
present *.md files (ignoring thirdparty).

It is useful not only for possible future tooling that would check the
markdown files syntax, but also as a configuration for editor plugins,
e.g. linter-markdown for atom-linter.

Refs: #7637
Refs: #7727
Refs: #7757
PR-URL: #7729
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Rich Trott <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Robert Jefe Lindstaedt <[email protected]>
MylesBorins pushed a commit that referenced this pull request Sep 28, 2016
This fixes a markdown formatting error in 2016-07-13 CTC meeting
minutes, __proto__ was rendered incorrectly.

This was found by remark-lint.

PR-URL: #7729
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Robert Jefe Lindstaedt <[email protected]>
addaleax added a commit to addaleax/node that referenced this pull request Sep 30, 2016
Use blockquotes instead of code blocks for stability markers in
the docs. Doing that:

- Makes the makers appear correctly when viewed e.g. on github.
- Allows remark-lint rules like `no-undefined-references` to work
  properly (nodejs#7729).

PR-URL: nodejs#7757
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Сковорода Никита Андреевич <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
MylesBorins pushed a commit that referenced this pull request Sep 30, 2016
Use blockquotes instead of code blocks for stability markers in
the docs. Doing that:

- Makes the makers appear correctly when viewed e.g. on github.
- Allows remark-lint rules like `no-undefined-references` to work
  properly (#7729).

PR-URL: #7757
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Сковорода Никита Андреевич <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
MylesBorins pushed a commit that referenced this pull request Sep 30, 2016
Use blockquotes instead of code blocks for stability markers in
the docs. Doing that:

- Makes the makers appear correctly when viewed e.g. on github.
- Allows remark-lint rules like `no-undefined-references` to work
  properly (#7729).

PR-URL: #7757
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Сковорода Никита Андреевич <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
MylesBorins pushed a commit that referenced this pull request Oct 10, 2016
Use blockquotes instead of code blocks for stability markers in
the docs. Doing that:

- Makes the makers appear correctly when viewed e.g. on github.
- Allows remark-lint rules like `no-undefined-references` to work
  properly (#7729).

PR-URL: #7757
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Сковорода Никита Андреевич <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
rvagg pushed a commit that referenced this pull request Oct 18, 2016
Specifies the configuration for remark-lint, a markdown linter.

This configuration does not cause any warnings on any of the currently
present *.md files (ignoring thirdparty).

It is useful not only for possible future tooling that would check the
markdown files syntax, but also as a configuration for editor plugins,
e.g. linter-markdown for atom-linter.

Refs: #7637
Refs: #7727
Refs: #7757
PR-URL: #7729
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Rich Trott <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Robert Jefe Lindstaedt <[email protected]>
rvagg pushed a commit that referenced this pull request Oct 18, 2016
This fixes a markdown formatting error in 2016-07-13 CTC meeting
minutes, __proto__ was rendered incorrectly.

This was found by remark-lint.

PR-URL: #7729
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Robert Jefe Lindstaedt <[email protected]>
rvagg pushed a commit that referenced this pull request Oct 18, 2016
Use blockquotes instead of code blocks for stability markers in
the docs. Doing that:

- Makes the makers appear correctly when viewed e.g. on github.
- Allows remark-lint rules like `no-undefined-references` to work
  properly (#7729).

PR-URL: #7757
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Сковорода Никита Андреевич <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
MylesBorins pushed a commit that referenced this pull request Oct 26, 2016
Specifies the configuration for remark-lint, a markdown linter.

This configuration does not cause any warnings on any of the currently
present *.md files (ignoring thirdparty).

It is useful not only for possible future tooling that would check the
markdown files syntax, but also as a configuration for editor plugins,
e.g. linter-markdown for atom-linter.

Refs: #7637
Refs: #7727
Refs: #7757
PR-URL: #7729
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Rich Trott <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Robert Jefe Lindstaedt <[email protected]>
MylesBorins pushed a commit that referenced this pull request Oct 26, 2016
This fixes a markdown formatting error in 2016-07-13 CTC meeting
minutes, __proto__ was rendered incorrectly.

This was found by remark-lint.

PR-URL: #7729
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Robert Jefe Lindstaedt <[email protected]>
MylesBorins pushed a commit that referenced this pull request Oct 26, 2016
Use blockquotes instead of code blocks for stability markers in
the docs. Doing that:

- Makes the makers appear correctly when viewed e.g. on github.
- Allows remark-lint rules like `no-undefined-references` to work
  properly (#7729).

PR-URL: #7757
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Сковорода Никита Андреевич <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
@MylesBorins MylesBorins mentioned this pull request Oct 26, 2016
@silverwind
Copy link
Contributor

Excuse me asking, but how does one run the markdown linter? Is it not included in make lint?

@ChALkeR
Copy link
Member Author

ChALkeR commented Nov 9, 2016

@silverwind Ah, the tooling is included in a separate PR: #8551

The current configuration works if you have remark-cli and remark-lint installed locally (e.g. an editor plugin).

The tooling PR got stalled because I didn't have enough time to fix CI support, but I'm going to continue that soon, and probably make the CI support a separate issue to get the tooling landed faster.

@silverwind
Copy link
Contributor

Thanks. I managed to run it with

yarn global add remark-cli
remark doc/api/*.md

We have 174 lines that exceed 80 characters, yay.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations. tools Issues and PRs related to the tools directory.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

9 participants