Skip to content

build: integrate markdownlint for documentation consistency - #49

Merged
JacksonFergusonDev merged 2 commits into
mainfrom
markdownlint
Feb 20, 2026
Merged

build: integrate markdownlint for documentation consistency#49
JacksonFergusonDev merged 2 commits into
mainfrom
markdownlint

Conversation

@JacksonFergusonDev

@JacksonFergusonDev JacksonFergusonDev commented Feb 20, 2026

Copy link
Copy Markdown
Owner

Motivation

Relying solely on relaxed global IDE settings for Markdown introduces parsing vulnerabilities when documentation is rendered across different engines (e.g., GitHub Flavored Markdown vs. strict CommonMark). Missing blank lines around fenced code blocks or contiguous list items can corrupt the Abstract Syntax Tree (AST), resulting in raw text nodes instead of the intended DOM structures.

This PR establishes a repository-level linting baseline to enforce AST-critical formatting while explicitly bypassing stylistic constraints (like strict line lengths) that often cause unnecessary diff churn.

Changes

  • +.markdownlint.yaml:
    • Establishes structural integrity rules (e.g., MD031/MD032 for block spacing, ATX-style headings, and consistent list markers).
    • Disables MD013 (line length) and MD033 (inline HTML) to preserve complex layouts and prevent URL breakage.
  • ~.pre-commit-config.yaml:
    • Adds the markdownlint-cli hook to automatically resolve standard formatting deviations locally.
  • ~.github/workflows/ci.yml:
    • Injects an npx --yes markdownlint-cli step into the CI pipeline to ensure documentation compliance.
  • Documentation Cleanup:
    • Applied automated fixes to README.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, and all internal documentation to satisfy the new linting requirements and resolve CI failures.

Testing

  • Verified pre-commit run --all-files correctly detects and auto-fixes syntax deviations.
  • Verified CI workflow successfully executes the linting step via npx across the entire file tree.
  • Confirmed documentation renders correctly after automated structural adjustments.

- Add `.markdownlint.yaml` with custom rules to enforce AST-safe Markdown without imposing arbitrary constraints like line length.
- Update `.pre-commit-config.yaml` to include the `markdownlint-cli` hook for local, automated formatting checks.
- Update `.github/workflows/ci.yml` to execute `markdownlint-cli` via `npx`, ensuring documentation compliance during the CI pipeline.
Apply automated fixes to README.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, and subdirectory READMEs. This aligns the entire documentation suite with the new `.markdownlint.yaml` configuration, correcting structural inconsistencies such as heading styles, list markers, and block-level spacing to ensure deterministic rendering.
@JacksonFergusonDev
JacksonFergusonDev merged commit ad092f5 into main Feb 20, 2026
4 checks passed
@JacksonFergusonDev
JacksonFergusonDev deleted the markdownlint branch February 20, 2026 20:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant