Skip to content

feat: add GitHub workflows for documentation quality checks #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wtfsayo merged 2 commits into from
Jul 11, 2025
Merged

feat: add GitHub workflows for documentation quality checks #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e30522d
feat: add GitHub workflows for documentation quality checks
wtfsayo Jul 11, 2025
fb4c4e6
fix: correct YAML syntax in workflow files
wtfsayo Jul 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
165 changes: 165 additions & 0 deletions .github/workflows/check-dead-links.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,165 @@
name: Check Dead Links

on:
schedule:
# Run every 6 hours
- cron: "0 */6 * * *"
workflow_dispatch: # Allow manual triggering

permissions:
contents: write
pull-requests: write
issues: write

jobs:
check-links:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
token: ${{ secrets.GITHUB_TOKEN }}

- name: Setup Git and Create Feature Branch
run: |
git config --global user.name "github-actions[bot]"
git config --global user.email "github-actions[bot]@users.noreply.github.com"

# Create unique branch name with timestamp
BRANCH_NAME="fix/dead-links-$(date +%Y%m%d-%H%M%S)"
echo "BRANCH_NAME=$BRANCH_NAME" >> $GITHUB_ENV

git checkout -b "$BRANCH_NAME"

- name: Fix Dead Links with Claude
id: claude-fix-links
uses: anthropics/claude-code-action@beta
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

# Direct prompt for fixing broken links automatically
direct_prompt: |
Check all links in the documentation for broken or dead links and automatically fix them. Track all changes made for the PR description.

**Instructions:**
1. Scan all MDX and MD files in the repository
2. Check for the following types of links:
- Internal relative links (e.g., /components/cards, ../guides/intro)
- External links (e.g., https://example.com)
- Anchor links (e.g., #section-name)

**For each broken link found, automatically apply the fix:**
- **For typos**: Correct the spelling/path
- **For moved files**: Update to the new location
- **For renamed files**: Use fuzzy matching to find and update to correct filename
- **For missing anchors**: Remove anchor or update to valid anchor
- **For external 404s**: Comment out with explanation or update to wayback machine
- **For redirect chains**: Update to the final destination URL

**Track each fix made:**
- File path and line number
- Original broken link
- New fixed link
- Confidence level of fix
- Type of fix applied

**Link Checking Rules:**
- Internal links should point to existing files
- Internal links should use relative paths starting from root (e.g., /api/reference)
- External links should return valid HTTP responses (not 404, 500, etc.)
- Skip checking localhost links
- Skip checking example.com or placeholder domains

**Fix Application Guidelines:**
- Apply high-confidence fixes automatically
- For medium confidence: Apply fix but add a comment
- For low confidence: Comment out the link with explanation
- Use fuzzy matching (threshold: 85%) for path corrections
- Check git history for recently moved/renamed files
- Preserve link text when updating URLs
- Group similar fixes in commits

**Output Summary (save as JSON for PR description):**
- Total links checked
- Number of broken links found
- Number of links fixed automatically
- Number of links requiring manual review
- List of all fixes applied with confidence levels
- Files modified count

# Allow Claude to use bash commands for link checking and file editing
allowed_tools: "Bash(find . -name '*.mdx' -o -name '*.md'),Bash(grep -n),Bash(sed -i),Bash(curl -I),EditFile(*)"

# Custom environment variables
claude_env: |
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
REPOSITORY: ${{ github.repository }}

- name: Check for Changes
id: check-changes
run: |
if [ -n "$(git status --porcelain)" ]; then
echo "changes=true" >> $GITHUB_OUTPUT
echo "Changes detected"
else
echo "changes=false" >> $GITHUB_OUTPUT
echo "No changes needed"
fi

- name: Commit and Push Changes
if: steps.check-changes.outputs.changes == 'true'
run: |
# Stage all changes
git add -A

# Create detailed commit message
git commit -m "fix: automated broken link fixes" \
-m "- Fixed internal broken links with correct paths" \
-m "- Updated moved/renamed file references" \
-m "- Resolved external link redirects" \
-m "- Corrected typos in link paths" \
-m "- Added comments for low-confidence fixes"

# Push the branch
git push origin "$BRANCH_NAME"

- name: Create Pull Request
if: steps.check-changes.outputs.changes == 'true'
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
# Create PR description with details from Claude's analysis
PR_BODY="## Automated Broken Link Fixes

This PR contains automated fixes for broken links detected by the scheduled workflow.

### Changes Made:
- 🔗 Fixed internal broken links
- 📁 Updated references to moved/renamed files
- 🌐 Resolved external link issues
- ✏️ Corrected typos in link paths
- 💭 Added comments for links requiring manual review

### Review Instructions:
Please review the changes to ensure:
1. All link fixes point to valid destinations
2. Link text remains appropriate for new URLs
3. Commented links are addressed appropriately
4. No content meaning was changed

### Files Modified:
Check the Files changed tab for a complete list of modifications.

---
*This PR was automatically generated by the dead links checker workflow.*"

# Create the PR using GitHub CLI
gh pr create \
--title "fix: automated broken link fixes" \
--body "$PR_BODY" \
--base main \
--head "$BRANCH_NAME" \
--label "documentation" \
--label "broken-links" \
--label "automated"
189 changes: 189 additions & 0 deletions .github/workflows/check-documentation-quality.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,189 @@
name: Check Documentation Quality

on:
schedule:
# Run every 6 hours
- cron: "0 */6 * * *"
workflow_dispatch: # Allow manual triggering

permissions:
contents: write
pull-requests: write
issues: write

jobs:
check-documentation-quality:
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
issues: read
id-token: write

steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
token: ${{ secrets.GITHUB_TOKEN }}

- name: Setup Git and Create Feature Branch
run: |
git config --global user.name "github-actions[bot]"
git config --global user.email "github-actions[bot]@users.noreply.github.com"

# Create unique branch name with timestamp
BRANCH_NAME="fix/documentation-quality-$(date +%Y%m%d-%H%M%S)"
echo "BRANCH_NAME=$BRANCH_NAME" >> $GITHUB_ENV

git checkout -b "$BRANCH_NAME"

- name: Fix Documentation Quality Issues with Claude
id: claude-fix-quality
uses: anthropics/claude-code-action@beta
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

# Direct prompt for fixing documentation quality issues
direct_prompt: |
Check all MDX files in the documentation for quality issues and automatically fix them. Track all changes made for the PR description.

**Quality Checks to Perform:**

1. **Double Header Issues:**
- Find MDX files that have YAML frontmatter with a title field AND also have an H1 heading (# Title) in the content
- This creates duplicate headers because Mintlify automatically generates an H1 from the frontmatter title
- This is a critical issue that affects page appearance and SEO

2. **Duplicate Content Detection:**
- Find sections of content that are duplicated across multiple files
- Look for:
- Identical paragraphs (minimum 50 words)
- Identical code examples
- Identical component configurations
- Nearly identical sections with minor variations
- Exclude common patterns like copyright notices or standard warnings

3. **Other Quality Issues:**
- Missing frontmatter fields (title or description)
- Empty description fields
- Inconsistent heading hierarchy (e.g., H3 following H1 without H2)
- Files with emojis instead of Mintlify icons
- Code blocks without language tags

**For each issue found, automatically fix it:**

**For Double Headers:**
- Remove the H1 heading from the content (keep only frontmatter)
- Ensure content starts properly after frontmatter
- Track: filename, line removed, original heading text

**For Duplicate Content:**
- If accidental duplication: Keep the first instance, remove others
- If strategic duplication: Add a comment explaining why
- For partial duplication: Consider extracting to a reusable component
- Track: files modified, content removed/consolidated

**For Other Issues:**
- Fix missing/empty frontmatter fields with appropriate defaults
- Fix heading hierarchy issues
- Replace emojis with appropriate Mintlify icons
- Add language tags to code blocks
- Track: all changes made with before/after context

**Fix Application Rules:**
- Make minimal, precise changes
- Preserve all content except what needs to be fixed
- Maintain proper MDX formatting
- Test that files remain valid MDX after changes
- Create clear commit messages for each type of fix

**Analysis Approach:**
1. First scan all MDX files to build a map of content
2. Check each file for double header issues
3. Use fuzzy matching to detect near-duplicates (85% similarity threshold)
4. Ignore common boilerplate text
5. Check for other quality issues

**Output Summary (save as JSON for PR description):**
- Total files scanned
- Number of double header issues fixed
- Number of duplicate content instances resolved
- Other quality issues fixed
- List of all files modified with specific changes
- Statistics on improvements made

# Allow Claude to use bash commands for finding and editing files
allowed_tools: "Bash(find . -name '*.mdx'),Bash(grep -n),Bash(head -n),Bash(sed -i),Bash(awk),EditFile(*)"

# Custom environment variables
claude_env: |
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
REPOSITORY: ${{ github.repository }}

- name: Check for Changes
id: check-changes
run: |
if [ -n "$(git status --porcelain)" ]; then
echo "changes=true" >> $GITHUB_OUTPUT
echo "Changes detected"
else
echo "changes=false" >> $GITHUB_OUTPUT
echo "No changes needed"
fi

- name: Commit and Push Changes
if: steps.check-changes.outputs.changes == 'true'
run: |
# Stage all changes
git add -A

# Create detailed commit message
git commit -m "fix: automated documentation quality improvements" \
-m "- Fixed double header issues where H1 followed frontmatter title" \
-m "- Resolved duplicate content across files" \
-m "- Fixed missing language tags in code blocks" \
-m "- Replaced emojis with Mintlify icons" \
-m "- Fixed heading hierarchy issues"

# Push the branch
git push origin "$BRANCH_NAME"

- name: Create Pull Request
if: steps.check-changes.outputs.changes == 'true'
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
# Create PR description with details from Claude's analysis
PR_BODY="## Automated Documentation Quality Fixes

This PR contains automated fixes for documentation quality issues detected by the scheduled workflow.

### Changes Made:
- 🔧 Fixed double header issues (H1 headings after frontmatter titles)
- 📝 Resolved duplicate content across files
- 💻 Added missing language tags to code blocks
- 🎨 Replaced emojis with Mintlify icons
- 📊 Fixed heading hierarchy issues

### Files Modified:
Check the Files changed tab for a complete list of modifications.

### Review Instructions:
Please review the changes to ensure:
1. All double headers have been properly removed
2. No content was accidentally deleted
3. The documentation still reads naturally
4. All MDX files remain valid

---
*This PR was automatically generated by the documentation quality workflow.*"

# Create the PR using GitHub CLI
gh pr create \
--title "fix: automated documentation quality improvements" \
--body "$PR_BODY" \
--base main \
--head "$BRANCH_NAME" \
--label "documentation" \
--label "automated"