search

sindresorhus / awesome-lint

Linter for Awesome lists
MIT License
611 stars 59 forks source link

Edge case scenarios #30

Open transitive-bullshit opened 6 years ago

transitive-bullshit commented 6 years ago

I've started running the up-to-date version of awesome-lint from #29 on various well-known awesome lists and want to clarify some common edge cases.

Should the following scenarios be considered valid?

Awesome Rules

awesome/toc

The "Related Lists" section isn't in the table of contents. Should I add this to the blacklist of section names such as "License" and "Contributing"?

awesome/list-item

These all error because they don't end with proper punctuation. One option would be to relax this rule to only end with proper punctuation if the last character is in a certain ascii whitelist set.

awesome-nodejs uses sub-lists in some parts, whereas other lists use sub-headers (### Promises) to separate related content. Should we allow these types of sub-lists?

Third-Party Rules

no-literal-urls

(Edit Aug 10 2018: removed multiple edge cases that we already support)

fabacab commented 6 years ago

This rule comes up a lot, and I feel like it's mostly noise. A lot of lists use * instead of - for list-items. Maybe we change the rule to enforce consistency instead of enforce one particular character type?

Consistency seems more important to me than enforcing the particular character used, especially because Markdown allows both. It is going to be extremely painful for a lot of contributors who use one or the other to have to coordinate a switch to the other character, and you'll lose a lot of interest from otherwise motivated contributors (such as myself) in the process.

sindresorhus commented 6 years ago

The "Related Lists" section isn't in the table of contents. Should I add this to the blacklist of section names such as "License" and "Contributing"?

👍

sparkly - Generate sparklines ▁▂▃▅▂▇ cat-ascii-faces - ₍˄·͈༝·͈˄₎◞ ̑̑ෆ⃛ (=ↀωↀ=)✧ (^･o･^)ﾉ”

Here the last part should be wrapped in a inline codeblock:

sparkly - Generate sparklines ▁▂▃▅▂▇.

Fixed: https://github.com/sindresorhus/awesome-nodejs/commit/58d97db3e787148fb0bfbe15f764cd37ac8a6112

why-is-node-running - Node.js is running but you don't know why?

Question mark should be allowed at the end. Exclamation mark too.

Should we allow these types of sub-lists?

Yes, but only one level down.

humanize-url - Humanize a URL: http://sindresorhus.com → sindresorhus.com.

What's wrong with literal URLs? I don't understand the benefit of wrapping it in <>?

itaisteinherz commented 6 years ago

Since non-linked sub-lists are allowed, shouldn't we allow linked sub-lists as well? This is the root cause of many of the current linting errors on the main repo:

❯ awesome-lint https://github.com/sindresorhus/awesome
✖ Linting

  readme.md:88:72
  ✖   88:72   List item link and description must be separated with a dash  awesome/list-item
  ✖   90:58   List item link and description must be separated with a dash  awesome/list-item
  ✖  108:57   List item link and description must be separated with a dash  awesome/list-item
  ✖  115:69   List item link and description must be separated with a dash  awesome/list-item
  ✖  130:64   List item link and description must be separated with a dash  awesome/list-item
  ✖  133:59   List item link and description must be separated with a dash  awesome/list-item
  ✖  158:57   List item link and description must be separated with a dash  awesome/list-item
  ✖  164:54   List item link and description must be separated with a dash  awesome/list-item
  ✖  183:65   List item link and description must be separated with a dash  awesome/list-item
  ✖  212:4    List item description must end with proper punctuation        awesome/list-item
  ✖  253:73   List item link and description must be separated with a dash  awesome/list-item
  ✖  256:4    List item description must end with proper punctuation        awesome/list-item
  ✖  275:77   List item link and description must be separated with a dash  awesome/list-item
  ✖  277:86   List item link and description must be separated with a dash  awesome/list-item
  ✖  281:108  List item link and description must be separated with a dash  awesome/list-item
  ✖  285:74   List item link and description must be separated with a dash  awesome/list-item
  ✖  291:4    List item description must end with proper punctuation        awesome/list-item
  ✖  368:4    List item description must end with proper punctuation        awesome/list-item
  ✖  478:4    List item description must end with proper punctuation        awesome/list-item
  ✖  503:4    List item description must end with proper punctuation        awesome/list-item
  ✖  528:4    List item description must end with proper punctuation        awesome/list-item
  ✖  538:4    List item description must end with proper punctuation        awesome/list-item

  22 errors

Also, should linked items with no description (hence not ending with proper punctuation) be allowed? There are already such items in the main repo (and this is the root cause of another big portion of the linting errors).

transitive-bullshit commented 6 years ago

@itaisteinherz I believe most of these issues are because of https://github.com/remarkjs/remark/issues/198. Specifically, remark incorrectly parses the sub-lists as part of the main list-item's description and the description is then considered invalid.