Skip to content

Commit fc10d78

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 bc8580c commit fc10d78

File tree

1 file changed

+325
-0
lines changed

1 file changed

+325
-0
lines changed

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

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

0 commit comments

Comments
 (0)