Skip to content

Commit e9d6082

Browse files
github-actions[bot]Copilotdsyme
authored
Add Markdown Linter workflow (#233)
Adds a new workflow that runs Super Linter markdown quality checks on all Markdown files in the repository and creates a prioritized GitHub issue report when violations are found. - workflows/markdown-linter.md: Adapted from gh-aw super-linter.md - docs/markdown-linter.md: Documentation page - README.md: Added entry under Code Improvement Workflows Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Don Syme <dsyme@users.noreply.github.com>
1 parent ec7d342 commit e9d6082

3 files changed

Lines changed: 212 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ You can use the "/plan" agent to turn the reports into actionable issues which c
7070
- [🧪 Daily Test Improver](docs/daily-test-improver.md) - Improve test coverage by adding meaningful tests to under-tested areas
7171
- [⚡ Daily Perf Improver](docs/daily-perf-improver.md) - Analyze and improve code performance through benchmarking and optimization
7272
- [📊 Repository Quality Improver](docs/repository-quality-improver.md) - Daily rotating analysis of repository quality across code, documentation, testing, security, and custom dimensions
73+
- [📝 Markdown Linter](docs/markdown-linter.md) - Run Markdown quality checks on all documentation files and get a prioritized issue report of violations
7374

7475
## Security Workflows
7576

‎docs/markdown-linter.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# 📝 Markdown Linter
2+
3+
> For an overview of all available workflows, see the [main README](../README.md).
4+
5+
**Run Markdown quality checks across all documentation files and get a prioritized issue report of violations**
6+
7+
The [Markdown Linter workflow](../workflows/markdown-linter.md?plain=1) runs the [Super Linter](https://github.com/super-linter/super-linter) tool on every Markdown file in your repository, then uses an AI agent to analyze the results and create a detailed GitHub issue listing each violation with suggested fixes. Only Markdown files are checked — other file types are unaffected.
8+
9+
## Installation
10+
11+
```bash
12+
# Install the 'gh aw' extension
13+
gh extension install github/gh-aw
14+
15+
# Add the workflow to your repository
16+
gh aw add-wizard githubnext/agentics/markdown-linter
17+
```
18+
19+
This walks you through adding the workflow to your repository.
20+
21+
## How It Works
22+
23+
```mermaid
24+
graph LR
25+
A[Scheduled Trigger] --> B[Run Super Linter]
26+
B --> C[Check Markdown Files]
27+
C --> D{Violations Found?}
28+
D -->|Yes| E[AI Analyzes Results]
29+
E --> F[Create Issue Report]
30+
D -->|No| G[Noop: All Clear]
31+
```
32+
33+
The workflow runs in two jobs. The first job runs Super Linter to lint all Markdown files and uploads the log as an artifact. The second job (the AI agent) downloads that log, categorizes violations by severity, and creates a prioritized GitHub issue with recommended fixes. Previous issues expire after 2 days to avoid accumulation.
34+
35+
## Usage
36+
37+
The workflow runs on weekdays at 2 PM UTC and can also be triggered manually via `workflow_dispatch`.
38+
39+
### Configuration
40+
41+
After editing run `gh aw compile` to update the workflow and commit all changes to the default branch.
42+
43+
### Customizing What Gets Linted
44+
45+
By default only Markdown files are validated (`VALIDATE_MARKDOWN: "true"`, `VALIDATE_ALL_CODEBASE: "false"`). To extend validation to other file types, add the appropriate `VALIDATE_*` environment variables to the Super Linter step. See the [Super Linter documentation](https://github.com/super-linter/super-linter#environment-variables) for a full list.

‎workflows/markdown-linter.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
---
2+
description: Runs Markdown quality checks using Super Linter and creates issues for violations
3+
on:
4+
workflow_dispatch:
5+
schedule:
6+
- cron: "0 14 * * 1-5" # 2 PM UTC, weekdays only
7+
permissions:
8+
contents: read
9+
actions: read
10+
issues: read
11+
pull-requests: read
12+
safe-outputs:
13+
create-issue:
14+
expires: 2d
15+
title-prefix: "[linter] "
16+
labels: [automation, code-quality]
17+
noop:
18+
engine: copilot
19+
name: Markdown Linter
20+
timeout-minutes: 15
21+
imports:
22+
- shared/reporting.md
23+
jobs:
24+
super_linter:
25+
runs-on: ubuntu-latest
26+
permissions:
27+
contents: read
28+
packages: read
29+
statuses: write
30+
steps:
31+
- name: Checkout repository
32+
uses: actions/checkout@v6.0.2
33+
with:
34+
fetch-depth: 0
35+
persist-credentials: false
36+
37+
- name: Super-linter
38+
uses: super-linter/super-linter@v8.5.0
39+
id: super-linter
40+
env:
41+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
42+
CREATE_LOG_FILE: "true"
43+
LOG_FILE: super-linter.log
44+
DEFAULT_BRANCH: main
45+
ENABLE_GITHUB_ACTIONS_STEP_SUMMARY: "true"
46+
VALIDATE_MARKDOWN: "true"
47+
VALIDATE_ALL_CODEBASE: "false"
48+
49+
- name: Check for linting issues
50+
id: check-results
51+
run: |
52+
if [ -f "super-linter.log" ] && [ -s "super-linter.log" ]; then
53+
if grep -qE "ERROR|WARN|FAIL" super-linter.log; then
54+
echo "needs-linting=true" >> "$GITHUB_OUTPUT"
55+
else
56+
echo "needs-linting=false" >> "$GITHUB_OUTPUT"
57+
fi
58+
else
59+
echo "needs-linting=false" >> "$GITHUB_OUTPUT"
60+
fi
61+
62+
- name: Upload super-linter log
63+
if: always()
64+
uses: actions/upload-artifact@v7
65+
with:
66+
name: super-linter-log
67+
path: super-linter.log
68+
retention-days: 7
69+
steps:
70+
- name: Download super-linter log
71+
uses: actions/download-artifact@v8
72+
with:
73+
name: super-linter-log
74+
path: /tmp/gh-aw/
75+
tools:
76+
cache-memory: true
77+
edit:
78+
bash:
79+
- "*"
80+
---
81+
82+
# Markdown Quality Report
83+
84+
You are an expert documentation quality analyst. Your task is to analyze the Super Linter Markdown output and create a comprehensive issue report for the repository maintainers.
85+
86+
## Context
87+
88+
- **Repository**: ${{ github.repository }}
89+
- **Triggered by**: @${{ github.actor }}
90+
- **Run ID**: ${{ github.run_id }}
91+
92+
## Your Task
93+
94+
1. **Read the linter output** from `/tmp/gh-aw/super-linter.log` using the bash tool
95+
2. **Analyze the findings**:
96+
- Categorize errors by severity (critical, high, medium, low)
97+
- Identify patterns in the errors
98+
- Determine which errors are most important to fix first
99+
- Note: This workflow only validates Markdown files
100+
3. **Create a detailed issue** with the following structure:
101+
102+
### Issue Title
103+
Use format: "Markdown Quality Report - [Date] - [X] issues found"
104+
105+
### Issue Body Structure
106+
107+
```markdown
108+
## 🔍 Markdown Linter Summary
109+
110+
**Date**: [Current date]
111+
**Total Issues Found**: [Number]
112+
**Run ID**: ${{ github.run_id }}
113+
114+
## 📊 Breakdown by Severity
115+
116+
- **Critical**: [Count and brief description]
117+
- **High**: [Count and brief description]
118+
- **Medium**: [Count and brief description]
119+
- **Low**: [Count and brief description]
120+
121+
## 📁 Issues by Category
122+
123+
### [Category/Rule Name]
124+
- **File**: `path/to/file`
125+
- Line [X]: [Error description]
126+
- Suggested fix: [How to resolve]
127+
128+
[Repeat for other categories]
129+
130+
## 🎯 Priority Recommendations
131+
132+
1. [Most critical issue to address first]
133+
2. [Second priority]
134+
3. [Third priority]
135+
136+
## 📋 Full Linter Output
137+
138+
<details>
139+
<summary>Click to expand complete linter log</summary>
140+
141+
```
142+
[Include the full linter output here]
143+
```
144+
145+
</details>
146+
147+
## 🔗 References
148+
149+
- [Link to workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
150+
- [Super Linter Documentation](https://github.com/super-linter/super-linter)
151+
```
152+
153+
## Important Guidelines
154+
155+
- **Be concise but thorough**: Focus on actionable insights
156+
- **Prioritize issues**: Not all linting errors are equal
157+
- **Provide context**: Explain why each type of error matters for documentation quality
158+
- **Suggest fixes**: Give practical recommendations
159+
- **Use proper formatting**: Make the issue easy to read and navigate
160+
- **If no errors found**: Call `noop` celebrating clean markdown
161+
162+
**Important**: Always call exactly one safe-output tool before finishing (`create_issue` or `noop`).
163+
164+
```json
165+
{"noop": {"message": "No action needed: [brief explanation of what was analyzed and why]"}}
166+
```

0 commit comments

Comments
 (0)