Skip to content

Commit 751ec60

Browse files
fidenciofidencio
committed
workflows: Ensure our .md files are correct
Again, completely vibe generated using Cursor AI. :-) Signed-off-by: Fabiano Fidêncio <ffidencio@nvidia.com>
1 parent f8fd910 commit 751ec60

File tree

1 file changed

+341
-0
lines changed

1 file changed

+341
-0
lines changed

‎.github/workflows/markdown-validation.yaml‎

Lines changed: 341 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,341 @@
1+
name: Markdown Validation
2+
3+
on:
4+
pull_request:
5+
types:
6+
- edited
7+
- opened
8+
- reopened
9+
- synchronize
10+
11+
jobs:
12+
markdown-lint:
13+
name: Markdown Lint
14+
runs-on: ubuntu-22.04
15+
steps:
16+
- name: Checkout code
17+
uses: actions/checkout@v4
18+
19+
- name: Run markdownlint
20+
uses: nosborn/github-action-markdown-cli@v3.3.0
21+
with:
22+
files: .
23+
config_file: .markdownlint.json
24+
ignore_files: |
25+
node_modules/
26+
.github/
27+
continue-on-error: true
28+
id: mdlint
29+
30+
- name: Create markdownlint config if not exists
31+
if: failure()
32+
run: |
33+
if [ ! -f .markdownlint.json ]; then
34+
cat > .markdownlint.json << 'EOF'
35+
{
36+
"default": true,
37+
"MD013": false,
38+
"MD033": false,
39+
"MD041": false
40+
}
41+
EOF
42+
echo "ℹ️ Created default .markdownlint.json config"
43+
fi
44+
45+
- name: Show markdown lint results
46+
if: steps.mdlint.outcome == 'failure'
47+
run: |
48+
echo "## ⚠️ Markdown Lint Issues Found" >> $GITHUB_STEP_SUMMARY
49+
echo "" >> $GITHUB_STEP_SUMMARY
50+
echo "### How to Fix:" >> $GITHUB_STEP_SUMMARY
51+
echo "1. Install markdownlint locally: \`npm install -g markdownlint-cli\`" >> $GITHUB_STEP_SUMMARY
52+
echo "2. Run \`markdownlint .\` to see all issues" >> $GITHUB_STEP_SUMMARY
53+
echo "3. Common issues:" >> $GITHUB_STEP_SUMMARY
54+
echo " - Missing blank lines around headers" >> $GITHUB_STEP_SUMMARY
55+
echo " - Inconsistent list formatting" >> $GITHUB_STEP_SUMMARY
56+
echo " - Trailing spaces" >> $GITHUB_STEP_SUMMARY
57+
echo " - Multiple consecutive blank lines" >> $GITHUB_STEP_SUMMARY
58+
echo "" >> $GITHUB_STEP_SUMMARY
59+
echo "4. Or add exceptions to .markdownlint.json if rules don't apply" >> $GITHUB_STEP_SUMMARY
60+
61+
- name: Fail if markdown lint found issues
62+
if: steps.mdlint.outcome == 'failure'
63+
run: exit 1
64+
65+
spell-check:
66+
name: Spell Check
67+
runs-on: ubuntu-22.04
68+
steps:
69+
- name: Checkout code
70+
uses: actions/checkout@v4
71+
72+
- name: Run spell check
73+
uses: streetsidesoftware/cspell-action@v6
74+
with:
75+
config: .cspell.json
76+
files: |
77+
**/*.md
78+
**/NOTES.txt
79+
incremental_files_only: false
80+
inline: warning
81+
continue-on-error: true
82+
id: spellcheck
83+
84+
- name: Create cspell config if not exists
85+
run: |
86+
if [ ! -f .cspell.json ]; then
87+
cat > .cspell.json << 'EOF'
88+
{
89+
"version": "0.2",
90+
"language": "en",
91+
"words": [
92+
"aarch64",
93+
"amd64",
94+
"apiVersion",
95+
"appVersion",
96+
"Argo",
97+
"CoCo",
98+
"coco",
99+
"containerd",
100+
"crio",
101+
"DaemonSet",
102+
"daemonset",
103+
"daemonsets",
104+
"dcache",
105+
"ghcr",
106+
"gpu",
107+
"heim",
108+
"Helm",
109+
"helmfile",
110+
"imagePullPolicy",
111+
"imagePullSecrets",
112+
"kata",
113+
"k3s",
114+
"k0s",
115+
"k8s",
116+
"kubeadm",
117+
"kubectl",
118+
"kubelet",
119+
"Kubernetes",
120+
"kube",
121+
"microk8s",
122+
"namespace",
123+
"nvidia",
124+
"nydus",
125+
"ppc64le",
126+
"qemu",
127+
"rke2",
128+
"RuntimeClass",
129+
"runtimeclass",
130+
"runtimeclasses",
131+
"s390x",
132+
"shim",
133+
"shims",
134+
"snp",
135+
"snapshotter",
136+
"systemctl",
137+
"tarball",
138+
"tarballs",
139+
"tdx",
140+
"x86",
141+
"yaml",
142+
"zypper"
143+
],
144+
"ignorePaths": [
145+
"node_modules/**",
146+
".git/**",
147+
"*.lock",
148+
"package-lock.json",
149+
"Chart.lock"
150+
]
151+
}
152+
EOF
153+
echo "✅ Created default .cspell.json config"
154+
fi
155+
156+
- name: Show spell check summary
157+
if: always()
158+
run: |
159+
if [ "${{ steps.spellcheck.outcome }}" = "failure" ]; then
160+
echo "## ⚠️ Spelling Issues Found" >> $GITHUB_STEP_SUMMARY
161+
echo "" >> $GITHUB_STEP_SUMMARY
162+
echo "### How to Fix:" >> $GITHUB_STEP_SUMMARY
163+
echo "1. Review the inline comments on changed lines" >> $GITHUB_STEP_SUMMARY
164+
echo "2. Fix genuine spelling errors" >> $GITHUB_STEP_SUMMARY
165+
echo "3. For technical terms or project-specific words, add them to .cspell.json:" >> $GITHUB_STEP_SUMMARY
166+
echo ' ```json' >> $GITHUB_STEP_SUMMARY
167+
echo ' "words": [' >> $GITHUB_STEP_SUMMARY
168+
echo ' "your-technical-term"' >> $GITHUB_STEP_SUMMARY
169+
echo ' ]' >> $GITHUB_STEP_SUMMARY
170+
echo ' ```' >> $GITHUB_STEP_SUMMARY
171+
echo "4. Run locally: \`npx cspell '**/*.md'\`" >> $GITHUB_STEP_SUMMARY
172+
else
173+
echo "## ✅ No Spelling Issues Found" >> $GITHUB_STEP_SUMMARY
174+
fi
175+
176+
- name: Fail if spell check found issues
177+
if: steps.spellcheck.outcome == 'failure'
178+
run: exit 1
179+
180+
link-check:
181+
name: Check Markdown Links
182+
runs-on: ubuntu-22.04
183+
steps:
184+
- name: Checkout code
185+
uses: actions/checkout@v4
186+
187+
- name: Check links in markdown files
188+
uses: gaurav-nelson/github-action-markdown-link-check@v1
189+
with:
190+
use-quiet-mode: 'no'
191+
use-verbose-mode: 'yes'
192+
config-file: '.markdown-link-check.json'
193+
continue-on-error: true
194+
id: linkcheck
195+
196+
- name: Create link check config if not exists
197+
run: |
198+
if [ ! -f .markdown-link-check.json ]; then
199+
cat > .markdown-link-check.json << 'EOF'
200+
{
201+
"ignorePatterns": [
202+
{
203+
"pattern": "^http://localhost"
204+
},
205+
{
206+
"pattern": "^https://example.com"
207+
}
208+
],
209+
"timeout": "20s",
210+
"retryOn429": true,
211+
"retryCount": 3,
212+
"fallbackRetryDelay": "30s",
213+
"aliveStatusCodes": [200, 206, 299, 403]
214+
}
215+
EOF
216+
echo "✅ Created default .markdown-link-check.json config"
217+
fi
218+
219+
- name: Show link check summary
220+
if: always()
221+
run: |
222+
if [ "${{ steps.linkcheck.outcome }}" = "failure" ]; then
223+
echo "## ⚠️ Broken Links Found" >> $GITHUB_STEP_SUMMARY
224+
echo "" >> $GITHUB_STEP_SUMMARY
225+
echo "### How to Fix:" >> $GITHUB_STEP_SUMMARY
226+
echo "1. Check the detailed output above for broken links" >> $GITHUB_STEP_SUMMARY
227+
echo "2. Update or remove broken links" >> $GITHUB_STEP_SUMMARY
228+
echo "3. For false positives, add to .markdown-link-check.json:" >> $GITHUB_STEP_SUMMARY
229+
echo ' ```json' >> $GITHUB_STEP_SUMMARY
230+
echo ' "ignorePatterns": [' >> $GITHUB_STEP_SUMMARY
231+
echo ' { "pattern": "^https://your-domain.com" }' >> $GITHUB_STEP_SUMMARY
232+
echo ' ]' >> $GITHUB_STEP_SUMMARY
233+
echo ' ```' >> $GITHUB_STEP_SUMMARY
234+
echo "4. Run locally: \`npx markdown-link-check README.md\`" >> $GITHUB_STEP_SUMMARY
235+
else
236+
echo "## ✅ All Links Valid" >> $GITHUB_STEP_SUMMARY
237+
fi
238+
239+
- name: Fail if link check found issues
240+
if: steps.linkcheck.outcome == 'failure'
241+
run: exit 1
242+
243+
grammar-check:
244+
name: Grammar Check
245+
runs-on: ubuntu-22.04
246+
steps:
247+
- name: Checkout code
248+
uses: actions/checkout@v4
249+
250+
- name: Set up Python
251+
uses: actions/setup-python@v5
252+
with:
253+
python-version: '3.x'
254+
255+
- name: Install language-tool-python
256+
run: |
257+
pip install language-tool-python
258+
259+
- name: Run grammar check
260+
id: grammar
261+
continue-on-error: true
262+
run: |
263+
cat > check_grammar.py << 'PYEOF'
264+
import language_tool_python
265+
import sys
266+
import glob
267+
import os
268+
269+
tool = language_tool_python.LanguageTool('en-US')
270+
271+
errors_found = False
272+
273+
# Check markdown files
274+
files_to_check = list(glob.glob('**/*.md', recursive=True))
275+
# Add NOTES.txt files
276+
files_to_check.extend(glob.glob('**/NOTES.txt', recursive=True))
277+
278+
for md_file in files_to_check:
279+
if '.github' in md_file or 'node_modules' in md_file:
280+
continue
281+
282+
print(f"\n🔍 Checking {md_file}...")
283+
284+
try:
285+
with open(md_file, 'r', encoding='utf-8') as f:
286+
content = f.read()
287+
288+
matches = tool.check(content)
289+
290+
if matches:
291+
errors_found = True
292+
print(f"⚠️ Found {len(matches)} potential issue(s) in {md_file}:")
293+
for match in matches[:10]: # Limit to first 10
294+
print(f" - Line {match.context}")
295+
print(f" Issue: {match.message}")
296+
if match.replacements:
297+
print(f" Suggestion: {', '.join(match.replacements[:3])}")
298+
if len(matches) > 10:
299+
print(f" ... and {len(matches) - 10} more issues")
300+
else:
301+
print(f"✅ No issues found")
302+
except Exception as e:
303+
print(f"⚠️ Could not check {md_file}: {e}")
304+
305+
if errors_found:
306+
print("\n⚠️ Grammar check found potential issues")
307+
print("Note: These are suggestions and may include false positives")
308+
sys.exit(1)
309+
else:
310+
print("\n✅ Grammar check passed")
311+
PYEOF
312+
313+
python check_grammar.py || echo "result=found_issues" >> $GITHUB_OUTPUT
314+
315+
- name: Show grammar check summary
316+
if: always()
317+
run: |
318+
if [ "${{ steps.grammar.outputs.result }}" = "found_issues" ]; then
319+
echo "## ⚠️ Grammar Suggestions Available" >> $GITHUB_STEP_SUMMARY
320+
echo "" >> $GITHUB_STEP_SUMMARY
321+
echo "### Note:" >> $GITHUB_STEP_SUMMARY
322+
echo "Grammar check found potential improvements. These are **suggestions only**" >> $GITHUB_STEP_SUMMARY
323+
echo "and may include false positives for technical documentation." >> $GITHUB_STEP_SUMMARY
324+
echo "" >> $GITHUB_STEP_SUMMARY
325+
echo "### How to Review:" >> $GITHUB_STEP_SUMMARY
326+
echo "1. Check the detailed output above" >> $GITHUB_STEP_SUMMARY
327+
echo "2. Apply suggestions that make sense" >> $GITHUB_STEP_SUMMARY
328+
echo "3. Ignore technical terms flagged incorrectly" >> $GITHUB_STEP_SUMMARY
329+
echo "4. Focus on:" >> $GITHUB_STEP_SUMMARY
330+
echo " - Subject-verb agreement" >> $GITHUB_STEP_SUMMARY
331+
echo " - Article usage (a/an/the)" >> $GITHUB_STEP_SUMMARY
332+
echo " - Common typos" >> $GITHUB_STEP_SUMMARY
333+
echo " - Punctuation" >> $GITHUB_STEP_SUMMARY
334+
else
335+
echo "## ✅ Grammar Check Passed" >> $GITHUB_STEP_SUMMARY
336+
fi
337+
338+
- name: Fail if grammar check found issues
339+
if: steps.grammar.outputs.result == 'found_issues'
340+
run: exit 1
341+

0 commit comments

Comments
 (0)