build: integrate markdownlint for documentation consistency - #49
Merged
Conversation
- 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
force-pushed
the
markdownlint
branch
from
February 20, 2026 20:18
e1a9e80 to
c048015
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:MD031/MD032for block spacing, ATX-style headings, and consistent list markers).MD013(line length) andMD033(inline HTML) to preserve complex layouts and prevent URL breakage.~.pre-commit-config.yaml:markdownlint-clihook to automatically resolve standard formatting deviations locally.~.github/workflows/ci.yml:npx --yes markdownlint-clistep into the CI pipeline to ensure documentation compliance.README.md,CODE_OF_CONDUCT.md,CONTRIBUTING.md, and all internal documentation to satisfy the new linting requirements and resolve CI failures.Testing
pre-commit run --all-filescorrectly detects and auto-fixes syntax deviations.npxacross the entire file tree.