Skip to content

Commit 7d22030

Browse files
elizabethtrykinelizabethtrykin
authored
Add claude pr review/style-guide for docs (#440)
1 parent c9216b5 commit 7d22030

File tree

1 file changed

+156
-0
lines changed

1 file changed

+156
-0
lines changed

‎.github/workflows/pr-review.yml‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
name: 📚 Documentation Review (Simple)
2+
3+
on:
4+
pull_request:
5+
types: [opened, synchronize, reopened]
6+
paths:
7+
- 'fern/**/*.mdx'
8+
- 'fern/**/*.yml'
9+
- 'fern/**/*.yaml'
10+
11+
jobs:
12+
review:
13+
runs-on: ubuntu-latest
14+
permissions:
15+
contents: read
16+
pull-requests: write
17+
18+
steps:
19+
- uses: actions/checkout@v4
20+
21+
- name: 📂 Get changed files
22+
id: changed-files
23+
uses: tj-actions/changed-files@v40
24+
with:
25+
files: |
26+
fern/**/*.mdx
27+
fern/**/*.yml
28+
fern/**/*.yaml
29+
30+
- name: ⚙️ Setup Node.js
31+
uses: actions/setup-node@v4
32+
with:
33+
node-version: '18'
34+
35+
- name: 🤖 Install Claude Code
36+
run: npm install -g @anthropic-ai/claude-code
37+
38+
- name: 🔍 Review documentation
39+
if: steps.changed-files.outputs.any_changed == 'true'
40+
env:
41+
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
42+
run: |
43+
echo "## 📝✨ Documentation Review by Claude 🤖" > review.md
44+
echo "" >> review.md
45+
echo "Hey there! 👋 I've reviewed your documentation changes against our style guidelines. Here's what I found:" >> review.md
46+
echo "" >> review.md
47+
48+
for file in ${{ steps.changed-files.outputs.all_changed_files }}; do
49+
echo "🔍 Reviewing $file..."
50+
51+
# Read file content
52+
content=$(cat "$file")
53+
54+
# Get review from Claude
55+
review=$(claude -p --output-format text "
56+
You are a friendly documentation reviewer. Review this documentation file against these specific guidelines:
57+
58+
## Core Principles to Check:
59+
- **Clarity**: Plain language, no jargon or unnecessary complexity
60+
- **Brevity**: Short sentences and paragraphs
61+
- **Task-orientation**: Logical step order that helps readers proceed
62+
- **Scannability**: Good headings, spacing, and components for quick review
63+
- **Outcome focus**: Every section supports user success
64+
65+
## Style Rules to Verify:
66+
- **Titles**: Only first word capitalized (unless proper noun)
67+
- **Subtitles**: Begin with 'Learn to...' for guides, otherwise concise
68+
- **Emojis**: Only when essential for comprehension
69+
- **Tone**: Direct, professional, friendly
70+
- **Links**: Descriptive text (not 'click here')
71+
- **Bold**: Used for key names/concepts
72+
73+
## Writing Style to Check:
74+
- **Active voice**: 'Connect the SDK' not 'SDK should be connected'
75+
- **Present tense**: 'Run' not 'You will run'
76+
- **Second person**: 'you' (reserve 'we' for collaborative tutorials)
77+
- **Intent before action**: Explain why, then how
78+
- **Concrete examples**: Code snippets over theory
79+
- **Consistent terminology**: Same terms used throughout
80+
81+
## MDX Components to Validate:
82+
- **Accordions**: Only for FAQ sections
83+
- **Callouts**: <Tip>, <Note>, <Warning>, <Error>, <Info>, <Check>
84+
- **Cards**: Proper title, icon, href format
85+
- **Steps**: <Steps> for sequential instructions (NOT numbered lists 1,2,3,4...)
86+
- **Frames**: For images with captions
87+
- **Tabs**: For organizing related content
88+
- **CodeBlocks**: For multi-language examples
89+
90+
## Specific Things to Flag:
91+
- **Numbered lists (1. 2. 3.)**: Should use <Steps> component instead
92+
- **'Click here' links**: Use descriptive link text
93+
- **Passive voice**: Convert to active voice
94+
- **Long paragraphs**: Break into shorter ones
95+
- **Missing context**: Code examples need explanation
96+
97+
## Front Matter to Check:
98+
- title: short and clear
99+
- subtitle: concise and helpful
100+
101+
File: $file
102+
Content:
103+
\`\`\`
104+
$content
105+
\`\`\`
106+
107+
Be helpful and encouraging! Use these emojis in your feedback:
108+
- 🚨 🔥 for major issues that need fixing
109+
- ⚠️ 🤔 for minor issues or improvements
110+
- 💡 ✨ for suggestions and ideas
111+
- ✅ 🎉 🚀 for things done well
112+
- 🎯 for specific improvements
113+
- 📝 for writing style issues
114+
- 🧩 for MDX component suggestions
115+
116+
**IMPORTANT**: If you see numbered lists (1. 2. 3. etc.), tell them to use the <Steps> component instead:
117+
118+
Example:
119+
Instead of:
120+
1. First step
121+
2. Second step
122+
3. Third step
123+
124+
Use:
125+
<Steps>
126+
<Step title="First step">Description</Step>
127+
<Step title="Second step">Description</Step>
128+
<Step title="Third step">Description</Step>
129+
</Steps>
130+
131+
Focus on the most impactful issues first. Keep it friendly and constructive.
132+
")
133+
134+
echo "### 📄 \`$file\`" >> review.md
135+
echo "$review" >> review.md
136+
echo "" >> review.md
137+
echo "---" >> review.md
138+
echo "" >> review.md
139+
done
140+
141+
echo "📖 [Style Guidelines](.cursorrules) | Thanks for contributing! 🙏✨" >> review.md
142+
143+
- name: 💬 Comment on PR
144+
if: steps.changed-files.outputs.any_changed == 'true'
145+
uses: actions/github-script@v7
146+
with:
147+
script: |
148+
const fs = require('fs');
149+
const review = fs.readFileSync('review.md', 'utf8');
150+
151+
await github.rest.issues.createComment({
152+
owner: context.repo.owner,
153+
repo: context.repo.repo,
154+
issue_number: context.issue.number,
155+
body: review
156+
});

0 commit comments

Comments
 (0)