Ref-003: Markdown Linting Standards

Type

Reference Documentation

Purpose

Defines the markdown quality enforcement strategy for the SEA-Forge™ platform using markdownlint to ensure consistent documentation style and catch common issues.

Tooling

Configuration

• Config File: .markdownlint.json
  • Contains project-specific rules and overrides
  • Centralized definition of markdown quality standards

NPM Scripts

• Command: npm run lint:md
  • Runs markdownlint against all **/*.md files
  • Uses repository configuration from .markdownlint.json

Usage

Local Development

1. Install Dependencies:

   1
   npm ci
   

2. Run Linter:

   1
   npm run lint:md
   

Continuous Integration

• Workflow: .github/workflows/markdownlint.yml
• Trigger: Pushes and pull requests to main branch
• Execution: npx markdownlint with repository config

Best Practices

1. Pre-PR Validation: Always run npm run lint:md before opening a pull request
2. Exception Handling:
   • Use inline ignore comments for file-specific exceptions
   • Update .markdownlint.json with justified exceptions when rules need relaxation
3. Consistency: Maintain markdown style uniformity across all documentation

Compliance Requirements

All markdown files (.md) MUST:

• Pass markdownlint checks before merge
• Follow rules defined in .markdownlint.json
• Document any exceptions with justification

Integration Points

• Works in conjunction with commit message standards (REF-002)
• Enforces quality for all spec documents generated by the DDD Compiler