docs(227): fix all markdown lint violations and add markdownlint config - #229
Conversation
🏗️ PR Added to Squad Triage QueueThis PR has been labeled with Next steps:
|
Test Results Summary273 tests 273 ✅ 16s ⏱️ Results for commit c6d7553. |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## dev #229 +/- ##
=======================================
Coverage 78.64% 78.64%
=======================================
Files 43 43
Lines 721 721
Branches 112 112
=======================================
Hits 567 567
Misses 108 108
Partials 46 46 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
This PR standardizes Markdown formatting across the repository by fixing markdownlint violations in docs, prompts, and Squad/Copilot skill files, and by adding a repo-wide .markdownlint.json configuration to keep future contributions consistent.
Changes:
- Added
.markdownlint.jsonto define project-wide markdownlint rules (notably MD013 line length, MD040 code fence languages, and MD060 table style). - Normalized Markdown formatting across many files (blank lines around headings/lists/code blocks, consistent table pipes, and corrected ordered list prefixes).
- Added language identifiers to fenced code blocks and wrapped long lines in several docs/blog posts.
Reviewed changes
Copilot reviewed 161 out of 176 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| .copilot/skills/agent-collaboration/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .copilot/skills/agent-conduct/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .copilot/skills/auth0-token-forwarding/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .copilot/skills/build-repair/SKILL.md | Markdown lint formatting fixes (tables/spacing). |
| .copilot/skills/ci-validation-gates/SKILL.md | Markdown lint formatting fixes (tables/spacing). |
| .copilot/skills/cli-wiring/SKILL.md | Markdown lint formatting fixes (tables/spacing). |
| .copilot/skills/client-compatibility/SKILL.md | Markdown lint formatting fixes (tables/spacing). |
| .copilot/skills/cross-squad/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .copilot/skills/distributed-mesh/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .copilot/skills/docs-standards/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .copilot/skills/economy-mode/SKILL.md | Markdown lint formatting fixes (tables/spacing). |
| .copilot/skills/external-comms/SKILL.md | Markdown lint formatting fixes (tables/spacing). |
| .copilot/skills/gh-auth-isolation/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .copilot/skills/git-workflow/SKILL.md | Markdown lint formatting fixes (tables/spacing). |
| .copilot/skills/github-multi-account/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .copilot/skills/history-hygiene/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .copilot/skills/init-mode/SKILL.md | Markdown lint formatting fixes (lists/code fences). |
| .copilot/skills/merged-pr-guard/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .copilot/skills/model-selection/SKILL.md | Markdown lint formatting fixes (tables/spacing). |
| .copilot/skills/mongodb-dba-patterns/SKILL.md | Markdown lint formatting fixes (tables/spacing). |
| .copilot/skills/personal-squad/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .copilot/skills/pre-push-test-gate/SKILL.md | Markdown lint formatting fixes (tables/spacing). |
| .copilot/skills/release-process/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .copilot/skills/reskill/SKILL.md | Markdown lint formatting fixes (tables/spacing). |
| .copilot/skills/reviewer-protocol/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .copilot/skills/session-recovery/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .copilot/skills/squad-conventions/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .copilot/skills/test-discipline/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .copilot/skills/testcontainers-shared-fixture/SKILL.md | Markdown lint formatting fixes (tables/spacing). |
| .copilot/skills/windows-compatibility/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .github/copilot-instructions.md | Markdown lint formatting fixes (lists/code fences). |
| .github/instructions/copilot-instructions.md | Markdown lint formatting fixes (code fence spacing). |
| .github/instructions/git-commit-instructions.md | Added code fence language identifiers + formatting fixes. |
| .github/instructions/markdown.instructions.md | Formatting tweaks to markdown standards doc (example text updated). |
| .github/instructions/mongo-dba.instructions.md | Markdown lint formatting fixes (spacing/structure). |
| .github/prompts/build-repair.prompt.md | Reformatted procedure lists for markdownlint compliance. |
| .github/prompts/copyright-header-update-prompt.md | Removed extraneous whitespace per markdownlint rules. |
| .github/prompts/create-readme.prompt.md | Converted bare URLs to proper Markdown link formatting and list normalization. |
| .github/prompts/editorconfig.prompt.md | Wrapped long lines + normalized list formatting. |
| .github/prompts/structured-autonomy-generate.prompt.md | Markdown lint formatting fixes (spacing/structure). |
| .github/prompts/structured-autonomy-plan.prompt.md | Fixed ordered list numbering consistency in workflow instructions. |
| .github/prompts/structured-autonomy.md | Added code fence language identifiers + removed extra blank lines. |
| .github/prompts/xunit-integration.prompt.md | Fixed malformed/indented code block into fenced block with language + formatting. |
| .github/prompts/xunit.prompt.md | Fixed heading level progression + indentation cleanup in examples. |
| .github/pull_request_template.md | Markdown lint formatting fixes (blank lines/section spacing). |
| .github/skills/bunit-test-migration/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .github/skills/github-issues/SKILL.md | Added code fence language identifiers + formatting fixes. |
| .github/skills/microsoft-docs/SKILL.md | Added code fence language identifiers + formatting fixes. |
| .github/skills/nuget-manager/SKILL.md | List formatting and spacing normalization for markdownlint. |
| .github/skills/refactor/SKILL.md | Added code fence language identifiers + formatting fixes. |
| .github/skills/tailwind-migration/SKILL.md | Added code fence language identifier (html) to example block. |
| .github/skills/vertical-slice/SKILL.md | Added code fence language identifier (text) to tree block. |
| .markdownlint.json | New repo-wide markdownlint configuration. |
| .squad/agents/aragorn/charter.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/agents/bilbo/charter.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/agents/bilbo/history.md | Removed stray whitespace-only content. |
| .squad/agents/boromir/charter.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/agents/frodo/charter.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/agents/frodo/history.md | Added markdownlint sweep entry + formatting fixes. |
| .squad/agents/gandalf/charter.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/agents/gandalf/history.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/agents/gimli/charter.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/agents/legolas/charter.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/agents/pippin/charter.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/agents/pippin/history.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/agents/ralph/charter.md | Removed extraneous whitespace per markdownlint rules. |
| .squad/agents/ralph/history.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/agents/sam/charter.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/agents/sam/history.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/agents/scribe/charter.md | Removed extraneous whitespace per markdownlint rules. |
| .squad/ceremonies.md | Normalized tables and spacing for markdownlint. |
| .squad/decisions-archive.md | Added blank lines for markdownlint compliance. |
| .squad/decisions/DELETED-ASSETS.md | Normalized table formatting for markdownlint. |
| .squad/identity/now.md | Added spacing for markdownlint compliance. |
| .squad/infrastructure-fix-summary.md | Added blank lines for markdownlint compliance. |
| .squad/playbooks/pr-merge-process.md | Markdown lint formatting fixes (tables/spacing). |
| .squad/playbooks/pre-push-process.md | Adjusted blockquote spacing for markdownlint compliance. |
| .squad/playbooks/release-myblog.md | Ordered list normalization per markdownlint. |
| .squad/playbooks/sprint-planning.md | Table formatting normalization per markdownlint. |
| .squad/routing.md | Table formatting normalization per markdownlint. |
| .squad/skills/auth0-management-api/SKILL.md | Markdown lint formatting fixes (tables/spacing). |
| .squad/skills/blazor-tailwind-theme-persistence/SKILL.md | Table formatting normalization per markdownlint. |
| .squad/skills/build-repair/SKILL.md | Table formatting normalization per markdownlint. |
| .squad/skills/building-protection/SKILL.md | Added spacing for markdownlint compliance. |
| .squad/skills/copilot-review-outdated-filter/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/skills/copilot-sdk-csharp-usage/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/skills/labels-feature-patterns/SKILL.md | Added spacing for markdownlint compliance. |
| .squad/skills/merged-pr-guard/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/skills/microsoft-code-reference/SKILL.md | Table formatting normalization per markdownlint. |
| .squad/skills/mongodb-dba-patterns/SKILL.md | Table formatting normalization per markdownlint. |
| .squad/skills/mongodb-filter-pattern/SKILL.md | Table formatting normalization per markdownlint. |
| .squad/skills/post-build-validation/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/skills/pre-push-test-gate/SKILL.md | Table formatting normalization per markdownlint. |
| .squad/skills/sprint-planning/SKILL.md | Added spacing for markdownlint compliance. |
| .squad/skills/squad-conventions/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/skills/testcontainers-shared-fixture/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/skills/webapp-testing/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/team.md | Table formatting normalization per markdownlint. |
| .squad/templates/casting-reference.md | Table formatting normalization per markdownlint. |
| .squad/templates/ceremonies.md | Table formatting normalization per markdownlint. |
| .squad/templates/cli-wiring.md | Table formatting normalization per markdownlint. |
| .squad/templates/cooperative-rate-limiting.md | Table formatting normalization per markdownlint. |
| .squad/templates/copilot-instructions.md | Markdown lint formatting fixes (lists/code fences). |
| .squad/templates/keda-scaler.md | Markdown lint formatting fixes (tables/spacing). |
| .squad/templates/machine-capabilities.md | Table formatting normalization per markdownlint. |
| .squad/templates/mcp-config.md | Added spacing for markdownlint compliance. |
| .squad/templates/orchestration-log.md | Table formatting normalization per markdownlint. |
| .squad/templates/plugin-marketplace.md | Added spacing for markdownlint compliance. |
| .squad/templates/ralph-circuit-breaker.md | Table formatting normalization per markdownlint. |
| .squad/templates/raw-agent-output.md | Added spacing for markdownlint compliance. |
| .squad/templates/roster.md | Table formatting normalization per markdownlint. |
| .squad/templates/routing.md | Table formatting normalization per markdownlint. |
| .squad/templates/run-output.md | Table formatting normalization per markdownlint. |
| .squad/templates/scribe-charter.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/templates/skill.md | Added standard blank lines between sections. |
| .squad/templates/skills/agent-collaboration/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/templates/skills/agent-conduct/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/templates/skills/ci-validation-gates/SKILL.md | Table formatting normalization per markdownlint. |
| .squad/templates/skills/cli-wiring/SKILL.md | Table formatting normalization per markdownlint. |
| .squad/templates/skills/client-compatibility/SKILL.md | Table formatting normalization per markdownlint. |
| .squad/templates/skills/cross-squad/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/templates/skills/distributed-mesh/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/templates/skills/docs-standards/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/templates/skills/economy-mode/SKILL.md | Table formatting normalization per markdownlint. |
| .squad/templates/skills/external-comms/SKILL.md | Table formatting normalization per markdownlint. |
| .squad/templates/skills/gh-auth-isolation/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/templates/skills/git-workflow/SKILL.md | Table formatting normalization per markdownlint. |
| .squad/templates/skills/github-multi-account/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/templates/skills/history-hygiene/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/templates/skills/init-mode/SKILL.md | Ordered list normalization per markdownlint. |
| .squad/templates/skills/model-selection/SKILL.md | Table formatting normalization per markdownlint. |
| .squad/templates/skills/personal-squad/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/templates/skills/release-process/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/templates/skills/reskill/SKILL.md | Table formatting normalization per markdownlint. |
| .squad/templates/skills/reviewer-protocol/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/templates/skills/session-recovery/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/templates/skills/squad-conventions/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/templates/skills/test-discipline/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| .squad/templates/skills/windows-compatibility/SKILL.md | Markdown lint formatting fixes (spacing/structure). |
| docs/adr/sprint8-architecture-tests-xunit-v3-rollout.md | Added blank lines around lists/headings per markdownlint. |
| docs/ARCHITECTURE.md | Added text code fence languages + spacing fixes throughout. |
| docs/AUTH0_SETUP.md | Added code fence language (text) + spacing fixes. |
| docs/blog/2026-04-18-myblog-project-kickoff.md | Wrapped long lines + added code fence language identifiers. |
| docs/blog/2026-04-20-release-v1-0-0.md | Spacing fixes around lists/headings. |
| docs/blog/2026-04-20-sprint-2-cqrs-mediatr.md | Added code fence language (text) + spacing fixes. |
| docs/blog/2026-04-20-sprint-3-e2e-tests-ci-hardening.md | Wrapped long lines + spacing fixes around lists/headings. |
| docs/blog/2026-04-24-release-v1-1-0.md | Wrapped long lines + added code fence language identifiers. |
| docs/blog/2026-04-24-release-v1-2-0.md | Wrapped long lines + spacing fixes around headings/code fences. |
| docs/blog/index.md | Inserted blank lines for markdownlint list/heading spacing rules. |
| docs/CODE_OF_CONDUCT.md | Normalized bullet list markers and indentation. |
| docs/CONTRIBUTING.md | Ordered list numbering and spacing normalization. |
| docs/SECRETS.md | Fixed a broken relative link to Auth0 setup documentation. |
| docs/SQUAD-COMMANDS.md | Added text code fence language identifiers + spacing fixes. |
| docs/sprint-8-xunit-v3-pilot-retro.md | Added text code fence language identifier + list spacing fixes. |
| docs/TESTING.md | Added text code fence language identifier + list spacing fixes. |
| docs/THEMING.md | Added text/css code fence language identifiers. |
| README.md | Added text code fence language + normalized table pipe spacing. |
| RELEASE.md | Added blank lines around headings/lists for markdownlint compliance. |
| 1. Ensure all untracked `.razor` and `.cs` files are staged or intentionally | ||
| excluded from git. | ||
|
|
||
| 3. Run the pre-push gates locally to catch errors early: | ||
| 2. Run the pre-push gates locally to catch errors early: | ||
|
|
| - **Headings**: Use `##` for H2 and `###` for H3. Ensure that headings are used in a hierarchical manner. Recommend restructuring if content includes H4, and more strongly recommend for H5. | ||
| - **Lists**: Use `-` for bullet points and `1.` for numbered lists. Indent nested lists with two spaces. | ||
| - **Code Blocks**: Use triple backticks (`) to create fenced code blocks. Specify the language after the opening backticks for syntax highlighting (e.g., `csharp). | ||
| - **Code Blocks**: Use triple backticks (`) to create fenced code blocks. Specify the language after the opening backticks for syntax highlighting (e.g.,`csharp). |
| 1. **Locate Solution File** | ||
| - Check for `*.slnx` file in current directory | ||
| - If found, continue to next step | ||
| - If not found, run: `cd ..` and check again | ||
| - Repeat until `*.slnx` file is found | ||
|
|
||
| 2. **Restore Dependencies** | ||
| - Run: `dotnet restore` | ||
|
|
||
| 3. **Build Solution** | ||
| - Run: `dotnet build --no-restore` | ||
| - Capture all build output, including errors and warnings. | ||
|
|
||
| 4. **Error & Warning Resolution** | ||
| - For each error or warning in the build output: | ||
| - Identify the affected file and line number. | ||
| - Research the error/warning code and message. | ||
| - Apply the recommended fix to the codebase. | ||
| - Rebuild the solution to verify the fix. | ||
| - Repeat until the build completes with zero errors and warnings. | ||
|
|
||
| 5. **Verification** | ||
| - Ensure the final build output shows “Build succeeded” and no warnings. | ||
| - Document any changes made to resolve issues. | ||
|
|
||
| 6. **Testing** | ||
| - Run unit tests to ensure the solution works as expected. | ||
| - If tests fail, identify and fix the issues in the codebase. | ||
| - Rebuild and retest until all tests pass. | ||
|
|
||
| 7. **Documentation** | ||
| - Create a `build-log.txt` file in the solution directory. | ||
| - Log all build outputs, error resolutions, and changes made. | ||
|
|
||
| - Check for `*.slnx` file in current directory | ||
| - If found, continue to next step | ||
| - If not found, run: `cd ..` and check again |
| | Gate | Command | Expected | | ||
| | ------------------------- | ---------------------------------------------------------------- | ------------------------------- | | ||
| | GitHub issue exists | `gh pr view <N> --json body -q .body \| grep -E "Closes #[0-9]+"` | Contains `Closes #N` | | ||
| | GitHub issue exists | `gh pr view <N> --json body -q .body \ | grep -E "Closes #[0-9]+"` | Contains `Closes #N` | |
| 1. **`.markdownlint.json` was pre-existing** — the worktree already had a comprehensive 24-line config | ||
| when the task started. Don't assume blank slate; always check first with `view`. |
- Add .markdownlint.json with project-wide lint rules (MD013 at 400 chars, MD033/MD041 off, MD060 consistent, etc.) - Fix MD040: add language identifiers to all fenced code blocks across README.md, ARCHITECTURE.md, AUTH0_SETUP.md, TESTING.md, THEMING.md, SQUAD-COMMANDS.md, blog posts, sprint retro, and .github skill/prompt files - Fix MD013: wrap long lines in blog post summaries and prompt files - Fix MD001: correct heading level jump in xunit.prompt.md - Fix MD046: reformat indented YAML block as fenced code in xunit-integration.prompt.md - Fix broken relative link in docs/SECRETS.md (Auth0 Setup Guide) - Auto-fix pass: MD032/MD022/MD031/MD029/MD012 blank-line/list violations - Remove temporary scripts/fix-md060.py helper script Closes #227 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> # Conflicts: # .squad/agents/bilbo/charter.md # .squad/routing.md # .squad/team.md
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
c6d7553 to
efae6eb
Compare
## Summary Adds a pre-commit git hook that runs `markdownlint-cli2` on staged `.md` files before each local commit, preventing formatting violations from ever entering commits. ## Changes - **`.github/hooks/pre-commit`** — new hook that: - Lints only staged `.md` files (fast: never scans the whole repo) - Uses repo `.markdownlint.json` config for consistent rules - Degrades gracefully if `markdownlint-cli2` is not installed (warns, does not block) - Exits 1 with clear file/rule output on violations; silent on success - **`scripts/install-hooks.sh`** — updated to install `pre-commit` alongside `pre-push`; updated summary message - **`package.json`** — adds `markdownlint-cli2 ^0.17.2` as dev dependency - **`package-lock.json`** — updated lockfile ## Testing - Staged a known-good `.md` file → hook exits 0 silently ✅ - Staged a `.md` file with violations → hook exits 1 with clear error output showing file and rule ✅ ## Context Follows up on PR #229 which fixed 3,243+ markdownlint violations and added `.markdownlint.json`. This gate prevents regressions at commit time. Working as Aragorn (Lead / Architect) --------- Co-authored-by: Boromir <boromir@squad.dev> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Summary
Working as Frodo (Tech Writer)
This PR resolves all markdown lint violations across the
MyBlogrepository and adds a.markdownlint.jsonconfiguration to enforce standards going forward.Closes #227
Changes
New File
.markdownlint.json— project-wide lint config (MD013@400, MD033/MD041 off, MD060 consistent, etc.)Auto-fixed (markdownlint-cli --fix)
MD040 — Missing code fence language identifiers
Added language specifiers to all fenced code blocks across:
README.md,docs/ARCHITECTURE.md,docs/AUTH0_SETUP.md,docs/TESTING.md,docs/THEMING.mddocs/SQUAD-COMMANDS.md(8 blocks),docs/sprint-8-xunit-v3-pilot-retro.mddocs/blog/(2 posts),.github/skills/(multiple files),.github/prompts/(multiple files)textfor diagrams/CLI/trees,yaml/html/cssfor structured contentMD013 — Long line wrapping
editorconfig.prompt.mdMD001 — Heading level increment
h1 → h3jump inxunit.prompt.md(changed###→##)MD046 — Indented code block
xunit-integration.prompt.mdas fencedyamlblockBroken link fix
docs/SECRETS.md: broken link tosrc/Web/Auth/README.md→./AUTH0_SETUP.mdVerification