markdown.yml

name: Markdown

on:
  push:
    branches: [develop, main]
  pull_request:
    branches: [develop, main]

permissions:
  contents: read
  pull-requests: write

jobs:
  markdown-lint:
    name: Markdown Lint
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      - name: Set up Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run markdownlint
        run: npm run lint:md
        id: markdown-lint

      - name: Comment on PR if linting fails
        if: steps.markdown-lint.outcome == 'failure' && github.event_name == 'pull_request'
        uses: actions/github-script@v8
        with:
          script: |
            const marker = '<!-- markdown-lint-comment -->';
            const body = `${marker}\n❌ **Markdown Linting Failed**\n\nThis PR must resolve markdown formatting issues before merging:\n\n- Run \`npm run lint:md\` locally to see all issues\n- Run \`npm run lint:md:fix\` to automatically fix some issues\n- Check \`.markdownlint-cli2.jsonc\` for configured rules\n\nCommon issues:\n- Missing blank lines around headings\n- Missing blank lines around lists\n- Missing blank lines around code fences\n- Line length exceeds 120 characters\n\nSee [markdownlint rules](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md) for details.`;

            const { data: comments } = await github.rest.issues.listComments({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
            });

            const existingComment = comments.find(c => c.body.includes(marker));

            if (existingComment) {
              await github.rest.issues.updateComment({
                comment_id: existingComment.id,
                owner: context.repo.owner,
                repo: context.repo.repo,
                body: body
              });
            } else {
              await github.rest.issues.createComment({
                issue_number: context.issue.number,
                owner: context.repo.owner,
                repo: context.repo.repo,
                body: body
              });
            }