API Documentation

This page provides comprehensive API documentation for mdbook-lint's core libraries and rule implementations.

Core Library (mdbook-lint-core)

The mdbook-lint-core crate provides the foundational infrastructure for markdown linting.

Overview

The mdbook-lint-core crate provides:

• Plugin-based architecture for extensible rule sets
• AST and text-based linting with efficient document processing
• Violation reporting with detailed position tracking and severity levels
• Automatic fix infrastructure for correctable violations
• Configuration system for customizing rule behavior
• Document abstraction with markdown parsing via comrak

Architecture

The core follows a plugin-based architecture where rules are provided by external crates:

┌─────────────────┐
│   Application   │
└────────┬────────┘
         │
┌────────▼────────┐
│  PluginRegistry │ ◄─── Registers rule providers
└────────┬────────┘
         │
┌────────▼────────┐
│   LintEngine    │ ◄─── Orchestrates linting
└────────┬────────┘
         │
┌────────▼────────┐
│     Rules       │ ◄─── Individual rule implementations
└─────────────────┘

Key Components

Document Processing

• Document - Represents a markdown file with content and metadata
• Position - Tracks line/column positions for violations
• NodeContext - Provides AST node information during linting

Rule System

• Rule trait - Core interface for all linting rules
• AstRule - Rules that process markdown AST nodes
• TextRule - Rules that process raw text content
• RuleProvider - Plugin interface for rule registration

Violation Reporting

• Violation - Represents a linting issue with location and severity
• Severity - Error, Warning, or Info levels
• Fix - Automatic fix information for violations

Engine and Registry

• LintEngine - Main orchestrator for document linting
• PluginRegistry - Manages rule providers and configuration

Rulesets Library (mdbook-lint-rulesets)

The mdbook-lint-rulesets crate implements all linting rules.

Rule Implementation

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

• 55 standard markdown rules (MD001-MD060) based on the markdownlint specification
• 18 mdBook-specific rules (MDBOOK001-MDBOOK025) for mdBook project validation
• 10 content rules (CONTENT001-CONTENT011) for content quality checks
• Automatic fix support for many rules to correct issues automatically
• Configurable rules with sensible defaults

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-MDBOOK012, MDBOOK025)

These rules validate mdBook-specific requirements:

• MDBOOK001: Code blocks should have language tags for proper syntax highlighting
• MDBOOK002: Validate internal link paths and anchors
• MDBOOK003: SUMMARY.md should follow proper mdBook structure
• MDBOOK005: Detect orphaned files not referenced in SUMMARY.md
• MDBOOK006: Validate cross-reference links between chapters
• MDBOOK007: Validate file include syntax and paths
• MDBOOK008: Check rustdoc_include directive usage
• MDBOOK009: Validate playground directive syntax
• MDBOOK010: Check for invalid math block syntax
• MDBOOK011: Validate template include syntax
• MDBOOK012: Check file include range syntax
• MDBOOK025: Ensure proper heading structure in SUMMARY.md

Automatic Fixes

Many rules support automatic fixing to correct violations:

The public Fix coordinate contract is exact and half-open: start is included and end is excluded. Position lines and columns are 1-based, and columns count Unicode scalar values—not UTF-8 bytes, grapheme clusters, or display cells. Use Fix::byte_range(content) to obtain a validated UTF-8 byte range instead of maintaining rule-specific conversions.

Line endings are explicit. A position at a line's end is before its terminator; column 1 of the following line is after the complete LF or CRLF terminator. Therefore:

• start == end is an insertion and consumes no source text.
• Replacing line content without its terminator ends at that line's end column.
• Replacing a complete terminated line ends at column 1 of the next line.
• CRLF is atomic; no valid position falls between \r and \n.
• At EOF, a replacement adds a newline only when its replacement text contains one explicitly.

Rule authors can use Fix::insertion, Fix::line_replacement, and Fix::line_range_replacement to make these distinctions explicit.

Whitespace and Formatting

• MD009: Remove trailing spaces while preserving line breaks
• MD010: Convert tabs to spaces with configurable spacing
• MD012: Remove excessive consecutive blank lines
• MD018: Add space after hash in headings
• MD019: Remove multiple spaces after hash in headings
• MD020: Add missing spaces inside closed ATX headings
• MD021: Remove multiple spaces inside hash-surrounded headings
• MD023: Remove indentation from headings
• MD027: Remove spaces after blockquote markers
• MD030: Ensure proper spacing after list markers
• MD034: Replace bare URLs with proper link syntax
• MD047: Ensure files end with single newline

Coming Soon

• Additional formatting rules
• More sophisticated content restructuring
• Context-aware fixes for complex violations

Usage Examples

Basic Library Usage

#![allow(unused)]
fn main() {
use mdbook_lint_core::{PluginRegistry, LintEngine};
use mdbook_lint_rulesets::{StandardRuleProvider, MdBookRuleProvider};

// Create a registry with standard rules
let mut registry = PluginRegistry::new();
registry.register(StandardRuleProvider::new())?;
registry.register(MdBookRuleProvider::new())?;

// Create engine and lint a document
let engine = LintEngine::from_registry(registry);
let document = Document::from_file("README.md")?;
let violations = engine.lint_document(&document)?;
}

Custom Rule Implementation

#![allow(unused)]
fn main() {
use mdbook_lint_core::{Document, AstRule, Violation, Position};
use comrak::nodes::{AstNode, NodeValue};

pub struct MyCustomRule;

impl AstRule for MyCustomRule {
    fn id(&self) -> &'static str { "CUSTOM001" }
    fn description(&self) -> &'static str { "My custom rule" }
    
    fn lint_ast(&self, document: &Document, node: &AstNode) -> Vec<Violation> {
        // Your custom linting logic here
        Vec::new()
    }
}
}

Configuration Usage

#![allow(unused)]
fn main() {
use mdbook_lint_core::Config;

let config = Config::from_file(".mdbook-lint.toml")?;
let engine = LintEngine::from_config(config)?;
}

Individual Rule Documentation

Each rule provides detailed documentation including:

• Purpose and rationale - Why the rule exists
• Examples - Correct and incorrect markdown
• Configuration options - Customizable behavior
• Automatic fixes - What fixes are available
• Related rules - Connected or overlapping rules

Featured Rules

MD001 - Heading Increment

Ensures heading levels increment sequentially for proper document structure.

MD009 - No Trailing Spaces (Auto-fix)

Removes trailing whitespace while preserving intentional line breaks.

MDBOOK001 - Code Block Language Tags

Ensures code blocks have language tags for proper syntax highlighting in mdBook.

Quick Rule Reference

✓ indicates automatic fix support

Full API Reference

For complete API documentation with all types, traits, and functions:

Generate Documentation

# Generate and open documentation
cargo doc --open

# Generate documentation for all features
cargo doc --all-features --open

# Generate documentation without dependencies
cargo doc --no-deps --open

Online Documentation

• crates.io: mdbook-lint-core, mdbook-lint-rulesets
• Repository: GitHub documentation

Integration Patterns

mdBook Preprocessor

# book.toml
[preprocessor.lint]
fail-on-warnings = true

CI/CD Integration

# Fail build on any violations
mdbook-lint lint --fail-on-warnings docs/

# Auto-fix and commit changes
mdbook-lint lint --fix docs/
git add docs/
git commit -m "docs: auto-fix markdown violations"

Editor Integration

Configure your editor to run mdbook-lint on save for real-time feedback.