remark-lint rule to warn when list items violate a given style

remark-lint-list-item-style

This is a remark-lint rule to warn when list items violate a given capitalization or punctuation style. Also comes with full unicode support.

This rule picks up where the abandoned remark-lint-list-item-punctuation package left off.

Install
Usage
API
- Options
Examples
Related
Appendix
- Published Package Details
- License
Contributing and Support
- Contributors

Install

Due to the nature of the unified ecosystem, this package is ESM only and cannot be require'd.

To install:

npm install --save-dev remark-lint-list-item-style

Usage

For maximum flexibility, there are several ways this plugin can be invoked.

Via API

import { read } from 'to-vfile';
import { reporter } from 'vfile-reporter';
import { remark } from 'remark';
import remarkLint from 'remark-lint';
import remarkLintListItemStyle from 'remark-lint-list-item-style';

const file = await remark()
  .use(remarkLint)
  .use(remarkLintListItemStyle)
  .process(await read('example.md'));

console.log(reporter(file));

Via remark-cli

remark --use remark-lint --use lint-list-item-style README.md

Via unified configuration

In package.json:

  /* … */
  "remarkConfig": {
    "plugins": [
      "remark-lint-list-item-style"
      /* … */
    ]
  },
  /* … */

In .remarkrc.js:

module.exports = {
  plugins: [
    // …
    'lint-list-item-style'
  ]
};

In .remarkrc.mjs:

import remarkLintListItemStyle from 'remark-lint-list-item-style';

export default {
  plugins: [
    // …
    remarkLintListItemStyle
  ]
};

API

Detailed interface information can be found under docs/.

Options

All "RegExp" values below are assumed to be strings, and will be transformed into regular expression objects via the following expression: RegExp(value, 'gu').

This plugin recognizes the following options:

`checkPunctuation`

Valid values: false | RegExp[]
Default: ["(\\.|\\?|;|,|!|\\p{Emoji}\uFE0F|\\p{Emoji_Presentation})"]

Checks that the final character of each stringified list item matches at least one of the given values, including emojis.

To match all unicode punctuation characters, you could provide ["\p{P}"] instead of the default, but this will match characters like ) and ].

Alternatively, to prevent punctuation, you could provide ["\P{P}"].

Lines that consist solely of an image are ignored.

`checkFirstWord`

Valid values: false | "capitalize" | "lowercase"
Default: "capitalize"

Checks that the first word of each stringified list item paragraph begins with a non-lowercase character ("capitalize") or a non-uppercase character ("lowercase").

List items beginning with a link, image, checkbox, or inline code block are ignored.

`ignoredFirstWords`

Valid values: RegExp[]
Default: []

Words that would normally be checked with respect to the checkFirstWord option will be ignored if they match at least one of the given values. Use this option to prevent false positives (e.g. "iOS", "eBay").

List items beginning with a link, image, checkbox, or inline code block are already ignored and do not need to be specified here.

`checkListSpread`

Valid values: "first" | "final" | "first-and-final" | "each"
Default: "each"

Determines how checkPunctuation is applied to list items with spread children. Has no effect when checkPunctuation is false.

Examples

`ok-punctuation.md`

In

Please get:

- A.
- B?
- C!

Out

No messages.

`ok-first-word.md`

In

Please get:

*   Milk;
*   Eggs;
*   Coffee.

Out

No messages.

`ok-spread-each.md`

In

- Foo?

  Zulu!

  Bar.

- `baz`?

  Zulu 😅

  Qux ✨

- ![image](https://example.com)

  ![image](https://example.com)

  Quuux 🚀

- B.

  C.

  D.

- Nested.

  - Items.

    - That.

      - Are nested.

- ![image][1]

  ![i][1]

  ☠️

  Quuux.

1. Run this script in your browser to prevent 'AAA' masking from effecting your
   local session.

   ```javascript
   window._uxa = window._uxa || [];
   window._uxa.push(['trackConsentGranted']);
   ```

2. `do` something else.

   ```javascript
   console.log('ok');
   ```

   ```javascript
   c;
   ```

3. D.

   An example of that something would be as follows.

   ```javascript
   console.log('ok');
   ```

4. Even more.

   ```javascript
   console.log('ok');
   ```

   An example of that something would be as follows.

[1]: https://example.com

Out

No messages.

`ok-spread-paragraph.md`

In

- Foo  
  Zulu  
  Bar.

- Baz  
  Zulu  
  Qux.

- Quux  
  Zulu  
  Quuux.

Out

No messages.

`ok-spread-final.md`

When configured with { checkListSpread: 'final' }.

In

- `foo`

  Zulu

  Bar.

- [baz](https://google.com)

  Zulu

  Qux.

- Quux

  Zulu

  Quuux.

Out

No messages.

`not-ok-punctuation.md`

In

- Alpha
- Beta
- Delta
-

Out

1:3-1:8: "a" is not allowed to punctuate list item
2:3-2:7: "a" is not allowed to punctuate list item
3:3-3:8: "a" is not allowed to punctuate list item
4:1-4:2: empty list item without punctuation is not allowed

`not-ok-first-word.md`

In

- not [free](https://example.com),
- ![image](https://example.com).
- ![image][1].
- FREE!
- [free](https://example.com).
- [free][1].
- `free`.
- Free.
- [ ] free.
- [x] free.

[1]: https://example.com

Out

1:3-1:35: Inconsistent list item capitalization: "n" should be "N"

Notice how only the first line triggers a warning while the others do not.

`not-ok-spread-each.md`

In

- Foo

  Bar.

- \[Baz]

  Qux.

- Quuux.

  (Quux)

- Nested.

  - Items.

    - That.

      - Are nested

1. Run this script in your browser to prevent 'AAA' masking from effecting your
   local session

   ```javascript
   window._uxa = window._uxa || [];
   window._uxa.push(['trackConsentGranted']);
   ```

2. `do` something else

   ```javascript
   console.log('ok');
   ```

   ```javascript
   c;
   ```

3. D.

   An example of that something would be as follows

   ```javascript
   console.log('ok');
   ```

4. Even more.

   ```javascript
   console.log('ok');
   ```

   An example of that something would be the aforesaid

5. `this is a tricky one because the punctuation is contained within the quotes.`

Out

1:3-1:6: "o" is not allowed to punctuate list item
5:3-5:9: "]" is not allowed to punctuate list item
11:3-11:9: ")" is not allowed to punctuate list item
19:9-19:19: "d" is not allowed to punctuate list item
21:4-22:17: "n" is not allowed to punctuate list item
29:4-29:23: "e" is not allowed to punctuate list item
41:4-41:52: "s" is not allowed to punctuate list item
53:4-53:55: "d" is not allowed to punctuate list item
55:4-55:76: "" is not allowed to punctuate list item

Note the final error, which only occurs when a list item containing single inline code node runs afoul of the punctuation configuration.

`not-ok-first-word-spread.md`

In

- Foo.

  bar.

- Baz.

  qux.

- Quux.

  quuux.

Out

3:3-3:7 Inconsistent list item capitalization: "b" should be "B"
7:3-7:7 Inconsistent list item capitalization: "q" should be "Q"
11:3-11:9 Inconsistent list item capitalization: "q" should be "Q"

Related

remark-lint-list-item-punctuation — the abandoned predecessor to this package.
remark-lint-list-item-bullet-indent — warn when list item bullets are indented.
remark-lint-list-item-content-indent — warn when the content of a list item has mixed indentation.
remark-lint-list-item-spacing — warn when list looseness is incorrect.
remark-lint-list-item-indent — warn when the spacing between a list item’s bullet and its content violates a given style.

Appendix

Further documentation can be found under docs/.

Published Package Details

This is an ESM-only package built by Babel for use in Node.js versions that are not end-of-life. For TypeScript users, this package supports both "Node10" and "Node16" module resolution strategies.

Expand details

That means ESM source will load this package via import { ... } from ... or await import(...) and CJS source will load this package via dynamic import(). This has several benefits, the foremost being: less code shipped/smaller package size, avoiding dual package hazard entirely, distributables are not packed/bundled/uglified, and a drastically less complex build process.

The glaring downside, which may or may not be relevant, is that CJS consumers cannot require() this package and can only use import() in an asynchronous context. This means, in effect, CJS consumers may not be able to use this package at all.

Each entry point (i.e. ENTRY) in package.json's exports[ENTRY] object includes one or more export conditions. These entries may or may not include: an exports[ENTRY].types condition pointing to a type declaration file for TypeScript and IDEs, a exports[ENTRY].module condition pointing to (usually ESM) source for Webpack/Rollup, a exports[ENTRY].node and/or exports[ENTRY].default condition pointing to (usually CJS2) source for Node.js require/import and for browsers and other environments, and other conditions not enumerated here. Check the package.json file to see which export conditions are supported.

Note that, regardless of the { "type": "..." } specified in package.json, any JavaScript files written in ESM syntax (including distributables) will always have the .mjs extension. Note also that package.json may include the sideEffects key, which is almost always false for optimal tree shaking where appropriate.

License

See LICENSE.

Contributing and Support

New issues and pull requests are always welcome and greatly appreciated! 🤩 Just as well, you can star 🌟 this project to let me know you found it useful! ✊🏿 Or buy me a beer, I'd appreciate it. Thank you!

See CONTRIBUTING.md and SUPPORT.md for more information.

Contributors

See the table of contributors.