Skip to main content

Crate mdbook_lint_rulesets

Crate mdbook_lint_rulesets 

Source
Expand description

Modular rulesets for mdbook-lint

This crate provides comprehensive markdown linting rules for mdBook projects and general markdown files. Rules are organized into two main categories, each available as an optional feature.

§Overview

The mdbook-lint-rulesets crate implements the actual linting rules used by mdbook-lint. It provides:

  • 59 standard markdown rules (MD001-MD059) based on the markdownlint specification
  • 7 mdBook-specific rules (MDBOOK001-MDBOOK007) for mdBook project validation
  • Automatic fix support for many rules to correct issues automatically
  • Configurable rules with sensible defaults

§Features

  • standard (default): Standard markdown linting rules
  • mdbook (default): mdBook-specific linting rules
  • content: Content quality rules (CONTENT001-005) - optional, off by default

§Rule Categories

§Standard Markdown Rules (MD001-MD059)

These rules cover common markdown style and formatting issues:

  • Heading rules (MD001-MD003, MD018-MD025): Heading hierarchy, style, and formatting
  • List rules (MD004-MD007, MD029-MD032): List formatting, indentation, and consistency
  • Whitespace rules (MD009-MD012, MD027-MD028): Trailing spaces, blank lines, tabs
  • Link rules (MD034, MD039, MD042): URL formatting and link text
  • Code rules (MD038, MD040, MD046, MD048): Code block formatting and fencing
  • Emphasis rules (MD036-MD037, MD049-MD050): Bold and italic formatting

§mdBook-Specific Rules (MDBOOK001-MDBOOK007)

These rules validate mdBook-specific requirements:

  • MDBOOK001: Code blocks should have language tags
  • MDBOOK002: SUMMARY.md should follow mdBook structure
  • MDBOOK003: Internal links should be valid
  • MDBOOK004: Part titles should be formatted correctly
  • MDBOOK005: Chapter paths should be relative
  • MDBOOK006: Draft chapters should have content or be marked
  • MDBOOK007: Separator syntax should be correct

§Usage

§Basic Setup

use mdbook_lint_rulesets::{StandardRuleProvider, MdBookRuleProvider};
use mdbook_lint_core::PluginRegistry;

let mut registry = PluginRegistry::new();

// Register standard markdown rules
registry.register_provider(Box::new(StandardRuleProvider))?;

// Register mdBook-specific rules
registry.register_provider(Box::new(MdBookRuleProvider))?;

§Using with the Lint Engine

use mdbook_lint_core::{PluginRegistry, Document};
use mdbook_lint_rulesets::StandardRuleProvider;
use std::path::PathBuf;

// Create registry and register provider
let mut registry = PluginRegistry::new();
registry.register_provider(Box::new(StandardRuleProvider))?;

// Create engine with registered rules
let engine = registry.create_engine()?;

// Lint a document
let content = "# My Document\n\n## Section\n";
let doc = Document::new(content.to_string(), PathBuf::from("README.md"))?;
let violations = engine.lint_document(&doc)?;

§Automatic Fixes

Many rules support automatic fixing of violations. Rules with fix support include:

  • MD009: Remove trailing spaces
  • MD010: Replace hard tabs with spaces
  • MD012: Remove multiple consecutive blank lines
  • MD018: Add space after hash in ATX headings
  • MD019: Fix multiple spaces after hash
  • MD020: Remove spaces inside closed ATX headings
  • MD021: Fix multiple spaces inside closed ATX headings
  • MD023: Remove indentation from headings
  • MD027: Fix multiple spaces after blockquote symbol
  • MD030: Fix spaces after list markers
  • MD034: Wrap bare URLs in angle brackets
  • MD047: Ensure files end with single newline

§Configuration

Rules can be configured through the RuleConfig trait. Example configuration:

[rules.MD013]
line_length = 120
code_blocks = false

[rules.MD009]
br_spaces = 2
strict = false

§Quick Start (Library Usage)

For the simplest usage, use create_default_engine to get a pre-configured linting engine with all default rules:

use mdbook_lint_rulesets::create_default_engine;

let engine = create_default_engine().expect("Failed to create engine");

// Lint some content
let violations = engine.lint_content("# Hello\n\n\n\nWorld", "test.md").unwrap();

// Apply automatic fixes
let (fixed, unfixed) = engine.apply_fixes("# Test\n\t", &violations);

Re-exports§

pub use standard::StandardRuleProvider;
pub use mdbook::MdBookRuleProvider;
pub use content::ContentRuleProvider;

Modules§

content
Content quality linting rules (CONTENT001+)
mdbook
mdBook-specific linting rules (MDBOOK001-025)
standard
Standard markdown linting rules (MD001-MD060)

Structs§

Config
Core configuration for the linting engine
Document
Represents a parsed markdown document with position information
LintEngine
Markdown linting engine
PluginRegistry
Registry for managing rule providers and creating engines
RuleMetadata
Metadata about a rule’s status, category, and properties
RuleRegistry
Registry for managing linting rules
Violation
A violation found during linting

Enums§

MdBookLintError
Main error type for mdbook-lint operations
RuleCategory
Rule categories for grouping and filtering
RuleStability
Rule stability levels
Severity
Severity levels for violations

Traits§

Rule
Trait that all linting rules must implement
RuleProvider
Trait for rule providers to register rules with the engine

Functions§

create_default_engine
Create a pre-configured lint engine with all default rules.

Type Aliases§

Result
Result type alias for mdbook-lint operations