BMAD-METHOD/docs/documentation-standards/automated-checks.md

Automated Documentation Checks

Overview

This document outlines the automated checks implemented to ensure all BMAD Method documentation meets our quality standards. These checks run automatically during the documentation review process and must pass before documentation can be published.

Setup Instructions

Prerequisites

• Node.js 16+
• npm or yarn
• Access to the BMAD documentation repository

Installation

# Clone the repository
git clone https://github.com/bmad-method/documentation.git

# Install dependencies
cd documentation
npm install

Available Checks

1. Markdown Linting

We use markdownlint to enforce consistent markdown formatting.

# Run markdown linting
npm run lint:md

Rules Enforced:

• MD001: Header levels should only increment by one level at a time
• MD003: Header style (ATX-style headers)
• MD004: Unordered list style (consistent markers)
• MD007: Unordered list indentation
• MD009: No trailing spaces
• MD010: No hard tabs
• MD011: No reversed link syntax
• MD012: Multiple consecutive blank lines
• MD013: Line length (flexible limit: 120 characters)
• MD018: No space after hash on atx style header
• MD019: Multiple spaces after hash on atx style header
• MD022: Headers should be surrounded by blank lines
• MD023: Headers must start at the beginning of the line
• MD025: Single title/h1 per file
• MD031: Fenced code blocks should be surrounded by blank lines
• MD032: Lists should be surrounded by blank lines
• MD034: No bare URLs
• MD037: No spaces inside emphasis markers
• MD038: No spaces inside code span elements
• MD039: No spaces inside link text
• MD040: Fenced code blocks should have a language specified
• MD041: First line in file should be a top level header
• MD047: Files should end with a single newline character

2. Spelling Check

We use cspell to check for spelling errors.

# Run spell check
npm run lint:spell

Features:

• Custom dictionary for BMAD-specific terminology
• Support for code snippets and technical terms
• Ignores URLs and code blocks
• Suggests corrections for misspelled words

3. Link Validation

We use a custom script to validate all links in the documentation.

# Run link validation
npm run lint:links

Checks:

• Internal links point to valid files
• External links are reachable (200 OK response)
• No broken anchor links
• No duplicate links
• No empty links

4. Accessibility Checks

We use a11y to check for accessibility issues.

# Run accessibility checks
npm run lint:a11y

Checks:

• Alt text for images
• Proper heading structure
• Sufficient color contrast
• Proper use of ARIA attributes
• Keyboard navigability

5. Style Guide Compliance

We use a custom script to check compliance with our style guide.

# Run style guide compliance check
npm run lint:style

Checks:

• Proper use of voice and tone
• Consistent terminology
• Proper use of formatting
• Adherence to file organization standards
• Consistent use of persona terminology

CI/CD Integration

These checks are integrated into our CI/CD pipeline and run automatically on pull requests.

# Example GitHub Actions workflow
name: Documentation Checks

on:
  pull_request:
    paths:
      - '**/*.md'
      - 'docs/**'

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '16'
      - run: npm install
      - run: npm run lint:md
      - run: npm run lint:spell
      - run: npm run lint:links
      - run: npm run lint:a11y
      - run: npm run lint:style

Pre-commit Hooks

You can set up pre-commit hooks to run these checks locally before committing:

# Install husky
npm install husky --save-dev

# Set up pre-commit hook
npx husky add .husky/pre-commit "npm run lint:all"

Troubleshooting

Common Issues

1. Markdown Linting Errors

   • Run npm run lint:md -- --fix to automatically fix some issues
   • Consult the markdownlint documentation for specific rule explanations

2. Spelling Errors

   • Add custom terms to .cspell.json
   • Use // cspell:ignore term for inline exceptions

3. Link Validation Errors

   • Check for typos in URLs
   • Ensure internal links use relative paths
   • Verify external resources are available

4. Accessibility Issues

   • Add alt text to all images
   • Maintain proper heading hierarchy
   • Use sufficient color contrast

Reporting Issues

If you encounter problems with the automated checks, please:

1. Create an issue in the BMAD Documentation Issues repository
2. Include the specific check that failed
3. Provide the error message and context
4. Suggest a potential solution if available

---

This document is maintained by the BMAD Documentation Team. Last updated: Current Date.