remark-lint-ordered-list-marker-style

remark-lint rule to warn when the markers of ordered lists violate a given style. This package helps maintain consistency in Markdown documents by ensuring ordered lists use either dots (.) or parentheses ()) consistently throughout the document.

Package Information

• Package Name: remark-lint-ordered-list-marker-style
• Package Type: npm
• Language: JavaScript (ESM)
• Installation: npm install remark-lint-ordered-list-marker-style

Core Imports

import remarkLintOrderedListMarkerStyle from 'remark-lint-ordered-list-marker-style';

Note: This package is ESM only and does not support CommonJS. Use dynamic imports in CommonJS environments:

// Not supported - package is ESM only
// const remarkLintOrderedListMarkerStyle = require('remark-lint-ordered-list-marker-style');

// Use dynamic import instead:
const remarkLintOrderedListMarkerStyle = (await import('remark-lint-ordered-list-marker-style')).default;

Basic Usage

import {remark} from 'remark';
import remarkLint from 'remark-lint';
import remarkLintOrderedListMarkerStyle from 'remark-lint-ordered-list-marker-style';

const processor = remark()
  .use(remarkLint)
  .use(remarkLintOrderedListMarkerStyle); // Uses 'consistent' by default

const result = await processor.process(`1.  First item

2)  Second item (inconsistent - will warn)`);

console.error(String(result));

Capabilities

Ordered List Marker Style Linting

Validates that ordered list markers are consistent throughout a Markdown document.

/**
 * remark-lint rule plugin for ordered list marker consistency
 * This is the default export - a unified plugin created with lintRule()
 */
declare const remarkLintOrderedListMarkerStyle: Plugin;

/**
 * Plugin type that accepts standard unified lint rule configuration
 * Supports: false (disable), true/'on' (enable), [severity, options], or direct options
 */
type Plugin = import('unified').Plugin<
  | []
  | [false]
  | [true | 'on' | 'warn' | 'error' | 0 | 1 | 2]
  | [boolean | 'on' | 'off' | 'warn' | 'error' | 0 | 1 | 2, Options?]
  | [Options]
, Root>;

type Options = 'consistent' | Marker;
type Marker = '.' | ')';

Configuration Options:

• 'consistent' (default): Detects the first ordered list marker style used in the document and enforces consistency with that style throughout
• '.': Enforces dot markers only (e.g., 1., 2., 3.)
• ')': Enforces parenthesis markers only (e.g., 1), 2), 3))

Usage Examples:

// Default behavior - consistent style detection
.use(remarkLintOrderedListMarkerStyle)
.use(remarkLintOrderedListMarkerStyle, 'consistent')

// Enforce dots only
.use(remarkLintOrderedListMarkerStyle, '.')

// Enforce parentheses only
.use(remarkLintOrderedListMarkerStyle, ')')

// Standard unified plugin configuration
.use(remarkLintOrderedListMarkerStyle, false)  // Disable rule
.use(remarkLintOrderedListMarkerStyle, true)   // Enable with default options
.use(remarkLintOrderedListMarkerStyle, [1, '.'])  // Severity 1 (warn) with dots
.use(remarkLintOrderedListMarkerStyle, [2, ')'])  // Severity 2 (error) with parens
.use(remarkLintOrderedListMarkerStyle, ['error', 'consistent'])  // Error severity

Error Messages:

When inconsistencies are found, the rule reports:

• "Marker style should be \.`"` - When dots are expected but parentheses found
• "Marker style should be \)`"` - When parentheses are expected but dots found
• "Incorrect ordered list item marker style \<invalid>`: use either `'.'` or `')'`"` - When invalid option provided

Types

/**
 * MDast Root node type (from @types/mdast)
 */
type Root = import('mdast').Root;

/**
 * Valid ordered list marker characters
 */
type Marker = '.' | ')';

/**
 * Configuration options for the rule
 */
type Options = 'consistent' | Marker;

/**
 * Unified plugin type supporting standard lint rule configuration
 * Based on unified-lint-rule conventions
 */
type Plugin = import('unified').Plugin<
  | []
  | [false]
  | [true | 'on' | 'warn' | 'error' | 0 | 1 | 2]
  | [boolean | 'on' | 'off' | 'warn' | 'error' | 0 | 1 | 2, Options?]
  | [Options]
, Root>;

/**
 * Rule metadata interface (from unified-lint-rule)
 */
interface RuleMeta {
  origin: string;
  url?: string | null;
}

/**
 * VFile interface for error reporting
 */
type VFile = import('vfile').VFile;

Integration

Unified Ecosystem

This package integrates seamlessly with the unified ecosystem:

• Unified Processor: Works with unified() processing pipeline
• Remark: Specifically designed for remark markdown processing
• Remark-lint: Requires remark-lint as the base linting framework
• VFile: Uses VFile for error reporting with position information

Configuration in Projects

Package.json configuration:

{
  "remarkConfig": {
    "plugins": [
      "remark-lint",
      ["remark-lint-ordered-list-marker-style", "."]
    ]
  }
}

CLI usage:

remark --use remark-lint --use remark-lint-ordered-list-marker-style example.md

Preset Integration

This rule is included in several remark-lint presets:

• remark-preset-lint-consistent: Uses 'consistent' setting
• remark-preset-lint-markdown-style-guide: Uses '.' setting
• remark-preset-lint-recommended: Uses '.' setting

Error Handling

The rule handles various edge cases:

• Generated nodes: Ignores programmatically generated list items
• Task list items: Properly extracts markers from checkbox lists
• Whitespace variations: Handles different spacing patterns around markers
• Invalid configurations: Provides clear error messages for unsupported options

Example error output:

3:1-3:8: Marker style should be `.`

This indicates line 3, column 1 through column 8 has a marker inconsistency.

Implementation Notes

How the Rule Works

The rule is built using unified-lint-rule and operates on the MDast (Markdown Abstract Syntax Tree):

1. AST Traversal: Uses unist-util-visit to traverse all list nodes in the syntax tree
2. Ordered List Detection: Filters for lists where node.ordered === true
3. Marker Extraction: Extracts the marker character from the source text using positional information
4. Consistency Check: Compares found markers against the configured option or established pattern
5. Error Reporting: Uses VFile to report position-specific errors

Source Code Behavior

Key implementation details from the source:

• Generated Node Handling: Uses unist-util-generated to skip programmatically generated nodes
• Task List Support: Removes checkbox syntax ([x], [ ]) before marker extraction using regex
• Whitespace Normalization: Strips whitespace and digits from extracted text to isolate markers
• Position Tracking: Uses unist-util-position for accurate error location reporting

Rule Origin

• Rule ID: remark-lint:ordered-list-marker-style
• Documentation URL: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-ordered-list-marker-style#readme

These details are automatically added to error messages by the unified-lint-rule framework.

Dependencies

Core dependencies required for functionality:

• @types/mdast: TypeScript definitions for Markdown AST
• unified: Core unified processor framework
• unified-lint-rule: Helper for creating lint rules
• unist-util-generated: Utility to check if AST nodes are generated
• unist-util-position: Utility for AST node position information
• unist-util-visit: Utility for traversing AST trees

Compatibility

• Node.js: 12.20+, 14.14+, 16.0+
• Environment: ESM only (not CommonJS compatible)
• Browser: Compatible via ESM imports from CDN (esm.sh)
• Deno: Compatible via esm.sh