[workshop-diagrams] Add theme-aware explanatory diagram for run error checks #811
Workflow file for this run
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: No See Also Sections or For-More-Details Footers | |
| on: | |
| pull_request: | |
| paths: | |
| - "**/*.md" | |
| - ".github/workflows/no-see-also.yml" | |
| push: | |
| branches: | |
| - main | |
| paths: | |
| - "**/*.md" | |
| - ".github/workflows/no-see-also.yml" | |
| permissions: | |
| contents: read | |
| issues: write | |
| jobs: | |
| no-see-also: | |
| name: Check for banned See Also sections and For-More-Details footers | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v6 | |
| - name: Check for banned patterns | |
| id: check | |
| continue-on-error: true | |
| uses: actions/github-script@v8 | |
| with: | |
| script: | | |
| const fs = require('fs') | |
| const path = require('path') | |
| const SEE_ALSO_RE = /^\s*##\s+(📚\s+)?See Also\s*$/m | |
| const FOR_MORE_DETAILS_RE = /^For more details, see /m | |
| function walkMdFiles(dir) { | |
| const results = [] | |
| for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { | |
| if (entry.name.startsWith('.')) continue | |
| const full = path.join(dir, entry.name) | |
| if (entry.isDirectory()) results.push(...walkMdFiles(full)) | |
| else if (entry.isFile() && entry.name.endsWith('.md')) results.push(full) | |
| } | |
| return results | |
| } | |
| const violations = [] | |
| for (const filepath of walkMdFiles('.')) { | |
| const raw = fs.readFileSync(filepath, 'utf8') | |
| const rel = filepath.replace(/^\.\//, '') | |
| if (SEE_ALSO_RE.test(raw)) { | |
| violations.push(rel) | |
| core.error( | |
| '"See Also" sections are not allowed. Use inline hyperlinks instead. See guidelines.md.', | |
| { file: rel } | |
| ) | |
| } | |
| if (FOR_MORE_DETAILS_RE.test(raw)) { | |
| violations.push(rel) | |
| core.error( | |
| '"For more details, see …" footers are not allowed. Link docs inline in the prose instead. See guidelines.md.', | |
| { file: rel } | |
| ) | |
| } | |
| } | |
| if (violations.length > 0) { | |
| core.setFailed( | |
| `Found ${violations.length} file(s) with banned patterns ("See Also" sections or "For more details" footers). ` + | |
| 'Remove them and link docs inline instead.' | |
| ) | |
| } else { | |
| core.info('No banned patterns found. All good.') | |
| } | |
| - name: File issue for violation on main | |
| if: steps.check.outcome == 'failure' && github.event_name == 'push' && github.ref == 'refs/heads/main' | |
| uses: actions/github-script@v8 | |
| with: | |
| script: | | |
| const title = 'Banned documentation pattern violation on main' | |
| const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}` | |
| const body = [ | |
| 'One or more markdown files contain a banned documentation pattern:', | |
| '- `## See Also` section, or', | |
| '- `For more details, see …` footer line.', | |
| '', | |
| `Workflow run: ${runUrl}`, | |
| '', | |
| 'Per the authoring guidelines, documentation links must appear as inline', | |
| 'hyperlinks in the prose — not in dedicated sections or trailing footers.', | |
| 'Please remove the patterns flagged in the workflow run.', | |
| ].join('\n') | |
| const { owner, repo } = context.repo | |
| const { data: searchResults } = await github.rest.search.issuesAndPullRequests({ | |
| q: `repo:${owner}/${repo} is:issue is:open in:title "${title}"`, | |
| per_page: 10, | |
| }) | |
| const existingIssue = searchResults.items.find( | |
| (issue) => issue.title === title | |
| ) | |
| if (existingIssue) { | |
| await github.rest.issues.createComment({ | |
| owner, | |
| repo, | |
| issue_number: existingIssue.number, | |
| body, | |
| }) | |
| } else { | |
| await github.rest.issues.create({ | |
| owner, | |
| repo, | |
| title, | |
| body, | |
| }) | |
| } | |
| - name: Fail job when violations found | |
| if: steps.check.outcome == 'failure' | |
| run: exit 1 |