Skip to content

Commit 992c592

Browse files
EdwardAngertEdwardAngert
committed
Enhance PR comment with informative status overview and collapsible sections
- Adds status overview with emoji indicators for each check - Organizes results into collapsible sections for better readability - Provides specific guidance on how to fix each type of issue - Includes detailed contextual information for Vale style issues - Makes output more scannable and actionable for contributors - Links to documentation for additional reference
1 parent 777bddc commit 992c592

File tree

1 file changed

+87
-20
lines changed

1 file changed

+87
-20
lines changed

‎.github/docs/actions/docs-shared/action.yaml

+87-20
Original file line numberDiff line numberDiff line change
@@ -501,42 +501,109 @@ runs:
501501
comment-id: ${{ steps.find-comment.outputs.comment-id }}
502502
issue-number: ${{ inputs.pr-number }}
503503
body: |
504-
## 📚 Docs Preview
504+
# 📚 Documentation Check Results
505505
506-
Your documentation changes are available for preview at:
507-
**🔗 [Documentation Preview](${{ steps.generate-preview.outputs.url }})**
506+
## 🔎 Status Overview
508507
509-
### Changed Documentation Files
510-
${{ steps.docs-analysis.outputs.formatted_files }}
508+
${{ steps.lint-docs.outputs.result == '' && '✅ **Markdown Linting**: No issues found' || '❌ **Markdown Linting**: Issues found' }}
509+
${{ steps.format-docs.outputs.result == '' && '✅ **Table Formatting**: No issues found' || '❌ **Table Formatting**: Issues found' }}
510+
${{ steps.lint-vale.outputs.result == '' && '✅ **Vale Style**: No issues found' || '❌ **Vale Style**: Issues found' }}
511+
${{ steps.cross-references.outputs.cross_ref_results == '' && '✅ **Cross-References**: No broken references' || '❌ **Cross-References**: Broken references found' }}
512+
${{ steps.check-links.outputs.result == '' && '✅ **Links**: All links are valid' || '⚠️ **Links**: Issues found' }}
511513
512-
${{ steps.docs-analysis.outputs.has_new_docs == 'true' && '### Newly Added Documentation' || '' }}
514+
## 🖥️ Preview Your Changes
515+
516+
${{ steps.generate-preview.outputs.url != '' && '**🔗 [View Documentation Preview](' || '' }}${{ steps.generate-preview.outputs.url }}${{ steps.generate-preview.outputs.url != '' && ')**' || 'No preview available' }}
517+
518+
<details>
519+
<summary><strong>📄 Changed Documentation Files</strong></summary>
520+
521+
${{ steps.docs-analysis.outputs.formatted_files || 'No documentation files changed' }}
522+
</details>
523+
524+
${{ steps.docs-analysis.outputs.has_new_docs == 'true' && '<details>' || '' }}
525+
${{ steps.docs-analysis.outputs.has_new_docs == 'true' && '<summary><strong>🆕 Newly Added Documentation</strong></summary>' || '' }}
513526
${{ steps.docs-analysis.outputs.has_new_docs == 'true' && steps.docs-analysis.outputs.new_docs || '' }}
514527
515-
${{ steps.docs-analysis.outputs.has_new_docs == 'true' && '### Preview Links for New Docs' || '' }}
528+
${{ steps.docs-analysis.outputs.has_new_docs == 'true' && '### Preview Links' || '' }}
516529
${{ steps.docs-analysis.outputs.has_new_docs == 'true' && steps.docs-analysis.outputs.preview_links || '' }}
530+
${{ steps.docs-analysis.outputs.has_new_docs == 'true' && '</details>' || '' }}
517531
518-
${{ steps.lint-docs.outputs.result != '' && '### Linting Issues' || '' }}
519-
${{ steps.lint-docs.outputs.result != '' && '```' || '' }}
532+
${{ steps.lint-docs.outputs.result != '' && '<details>' || '' }}
533+
${{ steps.lint-docs.outputs.result != '' && '<summary><strong>⚠️ Markdown Linting Issues</strong></summary>' || '' }}
534+
${{ steps.lint-docs.outputs.result != '' && '
535+
### How to Fix
536+
537+
Run these commands locally to fix or see detailed issues:
538+
```bash
539+
# To view issues
540+
npm run lint-docs
541+
542+
# Many issues can be fixed automatically with
543+
npm run lint-docs -- --fix
544+
```
545+
546+
### Issue Details
547+
```
548+
' || '' }}
520549
${{ steps.lint-docs.outputs.result != '' && steps.lint-docs.outputs.result || '' }}
521-
${{ steps.lint-docs.outputs.result != '' && '```' || '' }}
550+
${{ steps.lint-docs.outputs.result != '' && '```
551+
</details>' || '' }}
522552
523-
${{ steps.format-docs.outputs.result != '' && '### Markdown Table Formatting Issues' || '' }}
524-
${{ steps.format-docs.outputs.result != '' && 'Run `make fmt/markdown` locally to fix these issues:' || '' }}
525-
${{ steps.format-docs.outputs.result != '' && '```' || '' }}
553+
${{ steps.format-docs.outputs.result != '' && '<details>' || '' }}
554+
${{ steps.format-docs.outputs.result != '' && '<summary><strong>📏 Markdown Table Formatting Issues</strong></summary>' || '' }}
555+
${{ steps.format-docs.outputs.result != '' && '
556+
### How to Fix
557+
558+
Run this command locally to automatically fix all table formatting issues:
559+
```bash
560+
make fmt/markdown
561+
```
562+
563+
### Issue Details
564+
```
565+
' || '' }}
526566
${{ steps.format-docs.outputs.result != '' && steps.format-docs.outputs.result || '' }}
527-
${{ steps.format-docs.outputs.result != '' && '```' || '' }}
567+
${{ steps.format-docs.outputs.result != '' && '```
568+
</details>' || '' }}
528569
529-
${{ steps.lint-vale.outputs.result != '' && '### Vale Style Issues' || '' }}
530-
${{ steps.lint-vale.outputs.result != '' && '```' || '' }}
570+
${{ steps.lint-vale.outputs.result != '' && '<details>' || '' }}
571+
${{ steps.lint-vale.outputs.result != '' && '<summary><strong>📝 Vale Style Issues</strong></summary>' || '' }}
572+
${{ steps.lint-vale.outputs.result != '' && '
573+
### How to Fix
574+
575+
These style issues help maintain consistent documentation quality. Most Vale suggestions improve:
576+
577+
- Readability (sentence length, passive voice)
578+
- Consistency (terminology, capitalization)
579+
- Clarity (avoiding jargon, ambiguous wording)
580+
- Inclusivity (avoiding gendered or ableist language)
581+
582+
### Issue Details
583+
```
584+
' || '' }}
531585
${{ steps.lint-vale.outputs.result != '' && steps.lint-vale.outputs.result || '' }}
532-
${{ steps.lint-vale.outputs.result != '' && '```' || '' }}
586+
${{ steps.lint-vale.outputs.result != '' && '```
587+
</details>' || '' }}
533588
534-
${{ steps.cross-references.outputs.cross_ref_results != '' && '### Broken Cross-References' || '' }}
535-
${{ steps.cross-references.outputs.cross_ref_results != '' && 'The following cross-references may be broken due to file or heading changes:' || '' }}
589+
${{ steps.cross-references.outputs.cross_ref_results != '' && '<details>' || '' }}
590+
${{ steps.cross-references.outputs.cross_ref_results != '' && '<summary><strong>🔗 Broken Cross-References</strong></summary>' || '' }}
591+
${{ steps.cross-references.outputs.cross_ref_results != '' && '
592+
### How to Fix
593+
594+
The following changes in your PR may have broken existing references:
595+
596+
- For **deleted files**: Update or remove references to these files
597+
- For **renamed files**: Update links to use the new file path
598+
- For **removed headings**: Update or remove references to these headings
599+
600+
### Detected Issues
601+
' || '' }}
536602
${{ steps.cross-references.outputs.cross_ref_results != '' && steps.cross-references.outputs.cross_ref_results || '' }}
603+
${{ steps.cross-references.outputs.cross_ref_results != '' && '</details>' || '' }}
537604
538605
---
539-
<sub>🤖 This comment is automatically generated and updated when documentation changes.</sub>
606+
<sub>🤖 This comment is automatically generated and updated when documentation changes. [View Workflow](https://github.com/coder/coder/blob/main/.github/docs/README.md)</sub>
540607
edit-mode: replace
541608
reactions: eyes
542609
reactions-edit-mode: replace

0 commit comments

Comments
 (0)