From 286232259c7a94d43ab2d8d043cad43330399e27 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 4 Mar 2026 02:06:20 +0000 Subject: [PATCH] Add Markdown Linter workflow 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: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 1 + docs/markdown-linter.md | 45 ++++++++++ workflows/markdown-linter.md | 166 +++++++++++++++++++++++++++++++++++ 3 files changed, 212 insertions(+) create mode 100644 docs/markdown-linter.md create mode 100644 workflows/markdown-linter.md diff --git a/README.md b/README.md index 5563e65..358cba1 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,7 @@ You can use the "/plan" agent to turn the reports into actionable issues which c - [๐Ÿงช Daily Test Improver](docs/daily-test-improver.md) - Improve test coverage by adding meaningful tests to under-tested areas - [โšก Daily Perf Improver](docs/daily-perf-improver.md) - Analyze and improve code performance through benchmarking and optimization - [๐Ÿ“Š Repository Quality Improver](docs/repository-quality-improver.md) - Daily rotating analysis of repository quality across code, documentation, testing, security, and custom dimensions +- [๐Ÿ“ Markdown Linter](docs/markdown-linter.md) - Run Markdown quality checks on all documentation files and get a prioritized issue report of violations ## Security Workflows diff --git a/docs/markdown-linter.md b/docs/markdown-linter.md new file mode 100644 index 0000000..83818f9 --- /dev/null +++ b/docs/markdown-linter.md @@ -0,0 +1,45 @@ +# ๐Ÿ“ Markdown Linter + +> For an overview of all available workflows, see the [main README](../README.md). + +**Run Markdown quality checks across all documentation files and get a prioritized issue report of violations** + +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. + +## Installation + +```bash +# Install the 'gh aw' extension +gh extension install github/gh-aw + +# Add the workflow to your repository +gh aw add-wizard githubnext/agentics/markdown-linter +``` + +This walks you through adding the workflow to your repository. + +## How It Works + +```mermaid +graph LR + A[Scheduled Trigger] --> B[Run Super Linter] + B --> C[Check Markdown Files] + C --> D{Violations Found?} + D -->|Yes| E[AI Analyzes Results] + E --> F[Create Issue Report] + D -->|No| G[Noop: All Clear] +``` + +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. + +## Usage + +The workflow runs on weekdays at 2 PM UTC and can also be triggered manually via `workflow_dispatch`. + +### Configuration + +After editing run `gh aw compile` to update the workflow and commit all changes to the default branch. + +### Customizing What Gets Linted + +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. diff --git a/workflows/markdown-linter.md b/workflows/markdown-linter.md new file mode 100644 index 0000000..0338053 --- /dev/null +++ b/workflows/markdown-linter.md @@ -0,0 +1,166 @@ +--- +description: Runs Markdown quality checks using Super Linter and creates issues for violations +on: + workflow_dispatch: + schedule: + - cron: "0 14 * * 1-5" # 2 PM UTC, weekdays only +permissions: + contents: read + actions: read + issues: read + pull-requests: read +safe-outputs: + create-issue: + expires: 2d + title-prefix: "[linter] " + labels: [automation, code-quality] + noop: +engine: copilot +name: Markdown Linter +timeout-minutes: 15 +imports: + - shared/reporting.md +jobs: + super_linter: + runs-on: ubuntu-latest + permissions: + contents: read + packages: read + statuses: write + steps: + - name: Checkout repository + uses: actions/checkout@v6.0.2 + with: + fetch-depth: 0 + persist-credentials: false + + - name: Super-linter + uses: super-linter/super-linter@v8.5.0 + id: super-linter + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + CREATE_LOG_FILE: "true" + LOG_FILE: super-linter.log + DEFAULT_BRANCH: main + ENABLE_GITHUB_ACTIONS_STEP_SUMMARY: "true" + VALIDATE_MARKDOWN: "true" + VALIDATE_ALL_CODEBASE: "false" + + - name: Check for linting issues + id: check-results + run: | + if [ -f "super-linter.log" ] && [ -s "super-linter.log" ]; then + if grep -qE "ERROR|WARN|FAIL" super-linter.log; then + echo "needs-linting=true" >> "$GITHUB_OUTPUT" + else + echo "needs-linting=false" >> "$GITHUB_OUTPUT" + fi + else + echo "needs-linting=false" >> "$GITHUB_OUTPUT" + fi + + - name: Upload super-linter log + if: always() + uses: actions/upload-artifact@v7 + with: + name: super-linter-log + path: super-linter.log + retention-days: 7 +steps: + - name: Download super-linter log + uses: actions/download-artifact@v8 + with: + name: super-linter-log + path: /tmp/gh-aw/ +tools: + cache-memory: true + edit: + bash: + - "*" +--- + +# Markdown Quality Report + +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. + +## Context + +- **Repository**: ${{ github.repository }} +- **Triggered by**: @${{ github.actor }} +- **Run ID**: ${{ github.run_id }} + +## Your Task + +1. **Read the linter output** from `/tmp/gh-aw/super-linter.log` using the bash tool +2. **Analyze the findings**: + - Categorize errors by severity (critical, high, medium, low) + - Identify patterns in the errors + - Determine which errors are most important to fix first + - Note: This workflow only validates Markdown files +3. **Create a detailed issue** with the following structure: + +### Issue Title +Use format: "Markdown Quality Report - [Date] - [X] issues found" + +### Issue Body Structure + +```markdown +## ๐Ÿ” Markdown Linter Summary + +**Date**: [Current date] +**Total Issues Found**: [Number] +**Run ID**: ${{ github.run_id }} + +## ๐Ÿ“Š Breakdown by Severity + +- **Critical**: [Count and brief description] +- **High**: [Count and brief description] +- **Medium**: [Count and brief description] +- **Low**: [Count and brief description] + +## ๐Ÿ“ Issues by Category + +### [Category/Rule Name] +- **File**: `path/to/file` + - Line [X]: [Error description] + - Suggested fix: [How to resolve] + +[Repeat for other categories] + +## ๐ŸŽฏ Priority Recommendations + +1. [Most critical issue to address first] +2. [Second priority] +3. [Third priority] + +## ๐Ÿ“‹ Full Linter Output + +
+Click to expand complete linter log + +``` +[Include the full linter output here] +``` + +
+ +## ๐Ÿ”— References + +- [Link to workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) +- [Super Linter Documentation](https://github.com/super-linter/super-linter) +``` + +## Important Guidelines + +- **Be concise but thorough**: Focus on actionable insights +- **Prioritize issues**: Not all linting errors are equal +- **Provide context**: Explain why each type of error matters for documentation quality +- **Suggest fixes**: Give practical recommendations +- **Use proper formatting**: Make the issue easy to read and navigate +- **If no errors found**: Call `noop` celebrating clean markdown + +**Important**: Always call exactly one safe-output tool before finishing (`create_issue` or `noop`). + +```json +{"noop": {"message": "No action needed: [brief explanation of what was analyzed and why]"}} +```