Skip to content

Commit 569e3a1

Browse files
wtfsayowtfsayo
authored
Merge pull request #9 from elizaOS/feat/add-github-workflows
feat: add GitHub workflows for documentation quality checks
2 parents 2200542 + fb4c4e6 commit 569e3a1

File tree

2 files changed

+354
-0
lines changed

2 files changed

+354
-0
lines changed

‎.github/workflows/check-dead-links.yml‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
name: Check Dead Links
2+
3+
on:
4+
schedule:
5+
# Run every 6 hours
6+
- cron: "0 */6 * * *"
7+
workflow_dispatch: # Allow manual triggering
8+
9+
permissions:
10+
contents: write
11+
pull-requests: write
12+
issues: write
13+
14+
jobs:
15+
check-links:
16+
runs-on: ubuntu-latest
17+
steps:
18+
- name: Checkout repository
19+
uses: actions/checkout@v4
20+
with:
21+
fetch-depth: 0
22+
token: ${{ secrets.GITHUB_TOKEN }}
23+
24+
- name: Setup Git and Create Feature Branch
25+
run: |
26+
git config --global user.name "github-actions[bot]"
27+
git config --global user.email "github-actions[bot]@users.noreply.github.com"
28+
29+
# Create unique branch name with timestamp
30+
BRANCH_NAME="fix/dead-links-$(date +%Y%m%d-%H%M%S)"
31+
echo "BRANCH_NAME=$BRANCH_NAME" >> $GITHUB_ENV
32+
33+
git checkout -b "$BRANCH_NAME"
34+
35+
- name: Fix Dead Links with Claude
36+
id: claude-fix-links
37+
uses: anthropics/claude-code-action@beta
38+
with:
39+
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
40+
41+
# Direct prompt for fixing broken links automatically
42+
direct_prompt: |
43+
Check all links in the documentation for broken or dead links and automatically fix them. Track all changes made for the PR description.
44+
45+
**Instructions:**
46+
1. Scan all MDX and MD files in the repository
47+
2. Check for the following types of links:
48+
- Internal relative links (e.g., /components/cards, ../guides/intro)
49+
- External links (e.g., https://example.com)
50+
- Anchor links (e.g., #section-name)
51+
52+
**For each broken link found, automatically apply the fix:**
53+
- **For typos**: Correct the spelling/path
54+
- **For moved files**: Update to the new location
55+
- **For renamed files**: Use fuzzy matching to find and update to correct filename
56+
- **For missing anchors**: Remove anchor or update to valid anchor
57+
- **For external 404s**: Comment out with explanation or update to wayback machine
58+
- **For redirect chains**: Update to the final destination URL
59+
60+
**Track each fix made:**
61+
- File path and line number
62+
- Original broken link
63+
- New fixed link
64+
- Confidence level of fix
65+
- Type of fix applied
66+
67+
**Link Checking Rules:**
68+
- Internal links should point to existing files
69+
- Internal links should use relative paths starting from root (e.g., /api/reference)
70+
- External links should return valid HTTP responses (not 404, 500, etc.)
71+
- Skip checking localhost links
72+
- Skip checking example.com or placeholder domains
73+
74+
**Fix Application Guidelines:**
75+
- Apply high-confidence fixes automatically
76+
- For medium confidence: Apply fix but add a comment
77+
- For low confidence: Comment out the link with explanation
78+
- Use fuzzy matching (threshold: 85%) for path corrections
79+
- Check git history for recently moved/renamed files
80+
- Preserve link text when updating URLs
81+
- Group similar fixes in commits
82+
83+
**Output Summary (save as JSON for PR description):**
84+
- Total links checked
85+
- Number of broken links found
86+
- Number of links fixed automatically
87+
- Number of links requiring manual review
88+
- List of all fixes applied with confidence levels
89+
- Files modified count
90+
91+
# Allow Claude to use bash commands for link checking and file editing
92+
allowed_tools: "Bash(find . -name '*.mdx' -o -name '*.md'),Bash(grep -n),Bash(sed -i),Bash(curl -I),EditFile(*)"
93+
94+
# Custom environment variables
95+
claude_env: |
96+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
97+
REPOSITORY: ${{ github.repository }}
98+
99+
- name: Check for Changes
100+
id: check-changes
101+
run: |
102+
if [ -n "$(git status --porcelain)" ]; then
103+
echo "changes=true" >> $GITHUB_OUTPUT
104+
echo "Changes detected"
105+
else
106+
echo "changes=false" >> $GITHUB_OUTPUT
107+
echo "No changes needed"
108+
fi
109+
110+
- name: Commit and Push Changes
111+
if: steps.check-changes.outputs.changes == 'true'
112+
run: |
113+
# Stage all changes
114+
git add -A
115+
116+
# Create detailed commit message
117+
git commit -m "fix: automated broken link fixes" \
118+
-m "- Fixed internal broken links with correct paths" \
119+
-m "- Updated moved/renamed file references" \
120+
-m "- Resolved external link redirects" \
121+
-m "- Corrected typos in link paths" \
122+
-m "- Added comments for low-confidence fixes"
123+
124+
# Push the branch
125+
git push origin "$BRANCH_NAME"
126+
127+
- name: Create Pull Request
128+
if: steps.check-changes.outputs.changes == 'true'
129+
env:
130+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
131+
run: |
132+
# Create PR description with details from Claude's analysis
133+
PR_BODY="## Automated Broken Link Fixes
134+
135+
This PR contains automated fixes for broken links detected by the scheduled workflow.
136+
137+
### Changes Made:
138+
- 🔗 Fixed internal broken links
139+
- 📁 Updated references to moved/renamed files
140+
- 🌐 Resolved external link issues
141+
- ✏️ Corrected typos in link paths
142+
- 💭 Added comments for links requiring manual review
143+
144+
### Review Instructions:
145+
Please review the changes to ensure:
146+
1. All link fixes point to valid destinations
147+
2. Link text remains appropriate for new URLs
148+
3. Commented links are addressed appropriately
149+
4. No content meaning was changed
150+
151+
### Files Modified:
152+
Check the Files changed tab for a complete list of modifications.
153+
154+
---
155+
*This PR was automatically generated by the dead links checker workflow.*"
156+
157+
# Create the PR using GitHub CLI
158+
gh pr create \
159+
--title "fix: automated broken link fixes" \
160+
--body "$PR_BODY" \
161+
--base main \
162+
--head "$BRANCH_NAME" \
163+
--label "documentation" \
164+
--label "broken-links" \
165+
--label "automated"

‎.github/workflows/check-documentation-quality.yml‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
name: Check Documentation Quality
2+
3+
on:
4+
schedule:
5+
# Run every 6 hours
6+
- cron: "0 */6 * * *"
7+
workflow_dispatch: # Allow manual triggering
8+
9+
permissions:
10+
contents: write
11+
pull-requests: write
12+
issues: write
13+
14+
jobs:
15+
check-documentation-quality:
16+
runs-on: ubuntu-latest
17+
permissions:
18+
contents: write
19+
pull-requests: write
20+
issues: read
21+
id-token: write
22+
23+
steps:
24+
- name: Checkout repository
25+
uses: actions/checkout@v4
26+
with:
27+
fetch-depth: 0
28+
token: ${{ secrets.GITHUB_TOKEN }}
29+
30+
- name: Setup Git and Create Feature Branch
31+
run: |
32+
git config --global user.name "github-actions[bot]"
33+
git config --global user.email "github-actions[bot]@users.noreply.github.com"
34+
35+
# Create unique branch name with timestamp
36+
BRANCH_NAME="fix/documentation-quality-$(date +%Y%m%d-%H%M%S)"
37+
echo "BRANCH_NAME=$BRANCH_NAME" >> $GITHUB_ENV
38+
39+
git checkout -b "$BRANCH_NAME"
40+
41+
- name: Fix Documentation Quality Issues with Claude
42+
id: claude-fix-quality
43+
uses: anthropics/claude-code-action@beta
44+
with:
45+
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
46+
47+
# Direct prompt for fixing documentation quality issues
48+
direct_prompt: |
49+
Check all MDX files in the documentation for quality issues and automatically fix them. Track all changes made for the PR description.
50+
51+
**Quality Checks to Perform:**
52+
53+
1. **Double Header Issues:**
54+
- Find MDX files that have YAML frontmatter with a title field AND also have an H1 heading (# Title) in the content
55+
- This creates duplicate headers because Mintlify automatically generates an H1 from the frontmatter title
56+
- This is a critical issue that affects page appearance and SEO
57+
58+
2. **Duplicate Content Detection:**
59+
- Find sections of content that are duplicated across multiple files
60+
- Look for:
61+
- Identical paragraphs (minimum 50 words)
62+
- Identical code examples
63+
- Identical component configurations
64+
- Nearly identical sections with minor variations
65+
- Exclude common patterns like copyright notices or standard warnings
66+
67+
3. **Other Quality Issues:**
68+
- Missing frontmatter fields (title or description)
69+
- Empty description fields
70+
- Inconsistent heading hierarchy (e.g., H3 following H1 without H2)
71+
- Files with emojis instead of Mintlify icons
72+
- Code blocks without language tags
73+
74+
**For each issue found, automatically fix it:**
75+
76+
**For Double Headers:**
77+
- Remove the H1 heading from the content (keep only frontmatter)
78+
- Ensure content starts properly after frontmatter
79+
- Track: filename, line removed, original heading text
80+
81+
**For Duplicate Content:**
82+
- If accidental duplication: Keep the first instance, remove others
83+
- If strategic duplication: Add a comment explaining why
84+
- For partial duplication: Consider extracting to a reusable component
85+
- Track: files modified, content removed/consolidated
86+
87+
**For Other Issues:**
88+
- Fix missing/empty frontmatter fields with appropriate defaults
89+
- Fix heading hierarchy issues
90+
- Replace emojis with appropriate Mintlify icons
91+
- Add language tags to code blocks
92+
- Track: all changes made with before/after context
93+
94+
**Fix Application Rules:**
95+
- Make minimal, precise changes
96+
- Preserve all content except what needs to be fixed
97+
- Maintain proper MDX formatting
98+
- Test that files remain valid MDX after changes
99+
- Create clear commit messages for each type of fix
100+
101+
**Analysis Approach:**
102+
1. First scan all MDX files to build a map of content
103+
2. Check each file for double header issues
104+
3. Use fuzzy matching to detect near-duplicates (85% similarity threshold)
105+
4. Ignore common boilerplate text
106+
5. Check for other quality issues
107+
108+
**Output Summary (save as JSON for PR description):**
109+
- Total files scanned
110+
- Number of double header issues fixed
111+
- Number of duplicate content instances resolved
112+
- Other quality issues fixed
113+
- List of all files modified with specific changes
114+
- Statistics on improvements made
115+
116+
# Allow Claude to use bash commands for finding and editing files
117+
allowed_tools: "Bash(find . -name '*.mdx'),Bash(grep -n),Bash(head -n),Bash(sed -i),Bash(awk),EditFile(*)"
118+
119+
# Custom environment variables
120+
claude_env: |
121+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
122+
REPOSITORY: ${{ github.repository }}
123+
124+
- name: Check for Changes
125+
id: check-changes
126+
run: |
127+
if [ -n "$(git status --porcelain)" ]; then
128+
echo "changes=true" >> $GITHUB_OUTPUT
129+
echo "Changes detected"
130+
else
131+
echo "changes=false" >> $GITHUB_OUTPUT
132+
echo "No changes needed"
133+
fi
134+
135+
- name: Commit and Push Changes
136+
if: steps.check-changes.outputs.changes == 'true'
137+
run: |
138+
# Stage all changes
139+
git add -A
140+
141+
# Create detailed commit message
142+
git commit -m "fix: automated documentation quality improvements" \
143+
-m "- Fixed double header issues where H1 followed frontmatter title" \
144+
-m "- Resolved duplicate content across files" \
145+
-m "- Fixed missing language tags in code blocks" \
146+
-m "- Replaced emojis with Mintlify icons" \
147+
-m "- Fixed heading hierarchy issues"
148+
149+
# Push the branch
150+
git push origin "$BRANCH_NAME"
151+
152+
- name: Create Pull Request
153+
if: steps.check-changes.outputs.changes == 'true'
154+
env:
155+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
156+
run: |
157+
# Create PR description with details from Claude's analysis
158+
PR_BODY="## Automated Documentation Quality Fixes
159+
160+
This PR contains automated fixes for documentation quality issues detected by the scheduled workflow.
161+
162+
### Changes Made:
163+
- 🔧 Fixed double header issues (H1 headings after frontmatter titles)
164+
- 📝 Resolved duplicate content across files
165+
- 💻 Added missing language tags to code blocks
166+
- 🎨 Replaced emojis with Mintlify icons
167+
- 📊 Fixed heading hierarchy issues
168+
169+
### Files Modified:
170+
Check the Files changed tab for a complete list of modifications.
171+
172+
### Review Instructions:
173+
Please review the changes to ensure:
174+
1. All double headers have been properly removed
175+
2. No content was accidentally deleted
176+
3. The documentation still reads naturally
177+
4. All MDX files remain valid
178+
179+
---
180+
*This PR was automatically generated by the documentation quality workflow.*"
181+
182+
# Create the PR using GitHub CLI
183+
gh pr create \
184+
--title "fix: automated documentation quality improvements" \
185+
--body "$PR_BODY" \
186+
--base main \
187+
--head "$BRANCH_NAME" \
188+
--label "documentation" \
189+
--label "automated"

0 commit comments

Comments
 (0)