Fix/markdownlint readmes #3
Conversation
There was a problem hiding this comment.
Pull Request Overview
This PR fixes markdownlint CI failures (MD032: blanks-around-lists, MD013: line-length) and adds new documentation files for repository maintenance and PR workflow preferences.
- Fixed markdownlint MD032 and MD013 violations in language README files and contribution documentation
- Added a new maintenance subcategory README under PowerShell/system-administration
- Added PR_PREFERENCES.md documenting the repository's preference for using plain git with GitHub web UI
Reviewed Changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| PowerShell/system-administration/maintenance/README.md | New subcategory README documenting maintenance scripts organization and conventions |
| .github/PR_PREFERENCES.md | New documentation describing repository's preferred PR workflow using git and GitHub web UI |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Usage and placement | ||
|
|
||
| - Place small, single-purpose maintenance scripts here. | ||
| - For complex tools with multiple files, include a top-level README and a | ||
| subfolder with implementation files. | ||
|
|
||
| Naming and contribution | ||
|
|
||
| - Use descriptive kebab-case names, e.g. `clean-temp-folders.ps1` or | ||
| `check-service-health.ps1`. | ||
| - Add header documentation (comment-based help) and examples for each script. | ||
| - Include `-WhatIf` support for potentially destructive operations. | ||
|
|
||
| Examples |
There was a problem hiding this comment.
The section headings "Usage and placement", "Naming and contribution", and "Examples" should be formatted as proper Markdown headings (using ##) instead of plain text. This improves document structure and navigation.
| Usage and placement | |
| - Place small, single-purpose maintenance scripts here. | |
| - For complex tools with multiple files, include a top-level README and a | |
| subfolder with implementation files. | |
| Naming and contribution | |
| - Use descriptive kebab-case names, e.g. `clean-temp-folders.ps1` or | |
| `check-service-health.ps1`. | |
| - Add header documentation (comment-based help) and examples for each script. | |
| - Include `-WhatIf` support for potentially destructive operations. | |
| Examples | |
| ## Usage and placement | |
| - Place small, single-purpose maintenance scripts here. | |
| - For complex tools with multiple files, include a top-level README and a | |
| subfolder with implementation files. | |
| ## Naming and contribution | |
| - Use descriptive kebab-case names, e.g. `clean-temp-folders.ps1` or | |
| `check-service-health.ps1`. | |
| - Add header documentation (comment-based help) and examples for each script. | |
| - Include `-WhatIf` support for potentially destructive operations. | |
| ## Examples |
| - For complex tools with multiple files, include a top-level README and a | ||
| subfolder with implementation files. | ||
|
|
||
| Naming and contribution |
There was a problem hiding this comment.
The section heading "Naming and contribution" should be formatted as a proper Markdown heading (using ##) instead of plain text. This improves document structure and navigation.
| Naming and contribution | |
| ## Naming and contribution |
| - Add header documentation (comment-based help) and examples for each script. | ||
| - Include `-WhatIf` support for potentially destructive operations. | ||
|
|
||
| Examples |
There was a problem hiding this comment.
The section heading "Examples" should be formatted as a proper Markdown heading (using ##) instead of plain text. This improves document structure and navigation.
| Examples | |
| ## Examples |
| Examples | ||
|
|
||
| - `clean-temp-folders.ps1` — remove old files from temporary directories | ||
| - `rotate-logs.ps1` — rotate and compress rotating logs |
There was a problem hiding this comment.
Typo in comment: "rotating logs" should be "log files" for clarity. The phrase "rotate and compress rotating logs" is redundant.
| - `rotate-logs.ps1` — rotate and compress rotating logs | |
| - `rotate-logs.ps1` — rotate and compress log files |
| creating pull requests. This note documents that preference so contributors and | ||
| automation respect the chosen workflow. | ||
|
|
||
| Recommendations |
There was a problem hiding this comment.
The section headings "Recommendations" and "Why this preference" should be formatted as proper Markdown headings (using ##) instead of plain text. This improves document structure and navigation.
| - If you integrate other tools (for example GitKraken or GitHub Apps), only do | ||
| so after confirming credentials and access are explicitly authorized. | ||
|
|
||
| Why this preference |
There was a problem hiding this comment.
The section heading "Why this preference" should be formatted as a proper Markdown heading (using ##) instead of plain text. This improves document structure and navigation.
| Why this preference | |
| ## Why this preference |
|
@copilot open a new pull request to apply changes based on the comments in this thread |
Summary
Fix markdownlint failures reported by CI (MD032: blanks-around-lists, MD013: line-length).
Add a new README.md subcategory.
Add PR_PREFERENCES.md documenting the repo preference for using plain git + GitHub web PRs.
What I changed
Updated language README files to surround ordered lists with blank lines:
README.md
README.md
README.md
README.md
README.md
Reflowed long lines to satisfy line-length (<= 120 chars):
CONTRIBUTING.md
INSTRUCTIONS.md
README.md (small whitespace fix)
Added maintenance subcategory README:
README.md
Added PR preference guidance:
PR_PREFERENCES.md
Why
CI’s markdownlint job failed on MD032 and MD013 rules across several README and instruction files.
These edits are minimal, non-functional documentation changes to align the repo with the configured lint rules and keep CI green.
Verification performed
Ran locally: npx --yes markdownlint-cli "**/*.md" --config .markdownlint.json --ignore node_modules — no remaining failures were printed for the edits made.
Committed and pushed all changes to branch fix/markdownlint-readmes.
Ran Codacy CLI analyze for edited files (Codacy reported no applicable analyzers for Markdown files in this workspace; this is expected).
How to validate (recommended)
From repo root run:
npx --yes markdownlint-cli "**/*.md" --config .markdownlint.json --ignore node_modules
Confirm the GitHub Actions quality-check workflow runs and passes the markdownlint job.
Review changed README files for content and formatting clarity.
Notes & small decisions
I intentionally made minimal wording and whitespace edits; content meaning is preserved.
Added PR_PREFERENCES.md to document a repo preference: use git + GitHub web PRs instead of automating with the gh CLI (this was requested).
If CI flags any remaining issues, tell me the CI output and I’ll iterate.
Checklist
Fix MD032 (blanks around lists) in language READMEs
Fix MD013 (line length) in CONTRIBUTING.md and INSTRUCTIONS.md
Add README.md
Add PR_PREFERENCES.md
Run local markdownlint verification
Merge after CI passes and maintainers review