ci: add GitHub workflows for documentation validation and Mintlify checks #2047
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,208 @@ | ||
| name: Documentation Validation | ||
|
|
||
| on: | ||
| push: | ||
| branches: | ||
| - main | ||
| - master | ||
| pull_request: | ||
| branches: | ||
| - main | ||
| - master | ||
| workflow_dispatch: | ||
|
|
||
| jobs: | ||
| validate-docs: | ||
| name: Check for Errors and Broken Links | ||
| runs-on: ubuntu-latest | ||
|
|
||
| steps: | ||
| - name: Checkout repository | ||
| uses: actions/checkout@v4 | ||
| with: | ||
| fetch-depth: 0 | ||
|
|
||
| - name: Setup Node.js | ||
| uses: actions/setup-node@v4 | ||
viral-sangani marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| with: | ||
| node-version: '20' | ||
viral-sangani marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| cache: 'npm' | ||
|
|
||
| - name: Install Mintlify CLI | ||
| run: npm install -g mintlify | ||
|
|
||
| - name: Check for broken links | ||
| id: broken-links | ||
| continue-on-error: true | ||
| run: | | ||
| echo "## 🔍 Broken Links Check" >> $GITHUB_STEP_SUMMARY | ||
| echo "" >> $GITHUB_STEP_SUMMARY | ||
| if mint broken-links 2>&1 | tee broken-links-output.txt; then | ||
| echo "✅ No broken links found!" >> $GITHUB_STEP_SUMMARY | ||
| else | ||
| echo "❌ Broken links detected:" >> $GITHUB_STEP_SUMMARY | ||
| echo "\`\`\`" >> $GITHUB_STEP_SUMMARY | ||
| cat broken-links-output.txt >> $GITHUB_STEP_SUMMARY | ||
| echo "\`\`\`" >> $GITHUB_STEP_SUMMARY | ||
| exit 1 | ||
| fi | ||
|
|
||
| - name: Validate documentation structure | ||
viral-sangani marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| id: validate-structure | ||
| continue-on-error: true | ||
| run: | | ||
| echo "## 📋 Documentation Structure Check" >> $GITHUB_STEP_SUMMARY | ||
| echo "" >> $GITHUB_STEP_SUMMARY | ||
|
|
||
| # Check if docs.json exists | ||
| if [ ! -f "docs.json" ]; then | ||
| echo "❌ docs.json not found!" >> $GITHUB_STEP_SUMMARY | ||
| exit 1 | ||
| fi | ||
|
|
||
| # Validate JSON syntax | ||
| if jq empty docs.json 2>&1; then | ||
| echo "✅ docs.json is valid JSON" >> $GITHUB_STEP_SUMMARY | ||
| else | ||
| echo "❌ docs.json has invalid JSON syntax" >> $GITHUB_STEP_SUMMARY | ||
| exit 1 | ||
| fi | ||
|
|
||
| # Check for required fields | ||
| if jq -e '.name' docs.json > /dev/null; then | ||
| echo "✅ Required 'name' field present" >> $GITHUB_STEP_SUMMARY | ||
| else | ||
| echo "❌ Missing required 'name' field" >> $GITHUB_STEP_SUMMARY | ||
| exit 1 | ||
| fi | ||
|
|
||
| - name: Check for missing MDX files | ||
| id: check-mdx | ||
| continue-on-error: true | ||
| run: | | ||
| echo "## 📄 MDX Files Check" >> $GITHUB_STEP_SUMMARY | ||
| echo "" >> $GITHUB_STEP_SUMMARY | ||
|
|
||
| # Extract all page references from docs.json and check if files exist | ||
| missing_files=0 | ||
|
|
||
| # Find all .mdx references in navigation | ||
| jq -r '.. | .pages? // empty | .[] | select(type == "string")' docs.json | while read -r page; do | ||
| # Convert page path to file path | ||
| file_path="${page}.mdx" | ||
|
|
||
| if [ ! -f "$file_path" ] && [ ! -f "${page}.md" ]; then | ||
| echo "⚠️ Missing file: $file_path" >> $GITHUB_STEP_SUMMARY | ||
| missing_files=$((missing_files + 1)) | ||
| fi | ||
| done | ||
|
|
||
| if [ $missing_files -eq 0 ]; then | ||
| echo "✅ All referenced MDX files exist" >> $GITHUB_STEP_SUMMARY | ||
| else | ||
| echo "❌ Found $missing_files missing file(s)" >> $GITHUB_STEP_SUMMARY | ||
| exit 1 | ||
| fi | ||
|
|
||
| - name: Check for common MDX syntax errors | ||
| id: check-syntax | ||
| continue-on-error: true | ||
| run: | | ||
| echo "## ⚙️ MDX Syntax Check" >> $GITHUB_STEP_SUMMARY | ||
| echo "" >> $GITHUB_STEP_SUMMARY | ||
|
|
||
| errors=0 | ||
|
|
||
| # Find all MDX files | ||
| find . -name "*.mdx" -o -name "*.md" | while read -r file; do | ||
| # Skip node_modules and hidden directories | ||
| if [[ "$file" == *"node_modules"* ]] || [[ "$file" == *"/.git/"* ]]; then | ||
| continue | ||
| fi | ||
|
|
||
| # Check for unclosed JSX tags (basic check) | ||
| if grep -E '<[A-Z][a-zA-Z]*[^/>]*$' "$file" > /dev/null 2>&1; then | ||
| echo "⚠️ Potential unclosed JSX tag in: $file" >> $GITHUB_STEP_SUMMARY | ||
| errors=$((errors + 1)) | ||
| fi | ||
| done | ||
|
|
||
| if [ $errors -eq 0 ]; then | ||
| echo "✅ No obvious syntax errors detected" >> $GITHUB_STEP_SUMMARY | ||
| else | ||
| echo "⚠️ Found $errors potential syntax issue(s)" >> $GITHUB_STEP_SUMMARY | ||
| fi | ||
|
|
||
| - name: Final status check | ||
| if: always() | ||
| run: | | ||
| echo "## 🎯 Summary" >> $GITHUB_STEP_SUMMARY | ||
| echo "" >> $GITHUB_STEP_SUMMARY | ||
|
|
||
| all_passed=true | ||
|
|
||
| if [ "${{ steps.broken-links.outcome }}" != "success" ]; then | ||
| echo "- ❌ Broken links check failed" >> $GITHUB_STEP_SUMMARY | ||
| all_passed=false | ||
| else | ||
| echo "- ✅ Broken links check passed" >> $GITHUB_STEP_SUMMARY | ||
| fi | ||
|
|
||
| if [ "${{ steps.validate-structure.outcome }}" != "success" ]; then | ||
| echo "- ❌ Structure validation failed" >> $GITHUB_STEP_SUMMARY | ||
| all_passed=false | ||
| else | ||
| echo "- ✅ Structure validation passed" >> $GITHUB_STEP_SUMMARY | ||
| fi | ||
|
|
||
| if [ "${{ steps.check-mdx.outcome }}" != "success" ]; then | ||
| echo "- ❌ MDX files check failed" >> $GITHUB_STEP_SUMMARY | ||
| all_passed=false | ||
| else | ||
| echo "- ✅ MDX files check passed" >> $GITHUB_STEP_SUMMARY | ||
| fi | ||
|
|
||
| if [ "$all_passed" = false ]; then | ||
| echo "" >> $GITHUB_STEP_SUMMARY | ||
| echo "⚠️ Some checks failed. Please review the errors above." >> $GITHUB_STEP_SUMMARY | ||
| exit 1 | ||
| else | ||
| echo "" >> $GITHUB_STEP_SUMMARY | ||
| echo "🎉 All documentation checks passed successfully!" >> $GITHUB_STEP_SUMMARY | ||
| fi | ||
|
|
||
| - name: Comment PR with results | ||
| if: github.event_name == 'pull_request' && always() | ||
| uses: actions/github-script@v7 | ||
| with: | ||
| script: | | ||
| const fs = require('fs'); | ||
|
|
||
| let comment = '## 📚 Documentation Validation Results\n\n'; | ||
|
|
||
| // Add check results | ||
| comment += '### Check Status\n\n'; | ||
| comment += '| Check | Status |\n'; | ||
| comment += '|-------|--------|\n'; | ||
| comment += `| Broken Links | ${'${{ steps.broken-links.outcome }}' === 'success' ? '✅ Passed' : '❌ Failed'} |\n`; | ||
| comment += `| Structure | ${'${{ steps.validate-structure.outcome }}' === 'success' ? '✅ Passed' : '❌ Failed'} |\n`; | ||
| comment += `| MDX Files | ${'${{ steps.check-mdx.outcome }}' === 'success' ? '✅ Passed' : '❌ Failed'} |\n`; | ||
| comment += `| Syntax | ${'${{ steps.check-syntax.outcome }}' === 'success' ? '✅ Passed' : '⚠️ Warnings'} |\n`; | ||
|
|
||
| // Add broken links details if available | ||
| if (fs.existsSync('broken-links-output.txt')) { | ||
| const brokenLinks = fs.readFileSync('broken-links-output.txt', 'utf8'); | ||
| if (brokenLinks.trim()) { | ||
| comment += '\n### Broken Links Details\n\n```\n' + brokenLinks + '\n```\n'; | ||
| } | ||
| } | ||
|
|
||
| comment += '\n---\n'; | ||
| comment += '*This check was performed by the [Documentation Validation](.github/workflows/docs-validation.yml) workflow.*'; | ||
|
|
||
| github.rest.issues.createComment({ | ||
| issue_number: context.issue.number, | ||
| owner: context.repo.owner, | ||
| repo: context.repo.repo, | ||
| body: comment | ||
| }); | ||
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,50 @@ | ||
| name: Mintlify CI Checks | ||
|
|
||
| on: | ||
| push: | ||
| branches: | ||
| - main | ||
| - master | ||
| pull_request: | ||
| branches: | ||
| - main | ||
| - master | ||
|
|
||
| jobs: | ||
| mintlify-checks: | ||
| name: Run Mintlify CI Checks | ||
| runs-on: ubuntu-latest | ||
|
|
||
| steps: | ||
| - name: Checkout repository | ||
| uses: actions/checkout@v4 | ||
|
|
||
| - name: Setup Node.js | ||
| uses: actions/setup-node@v4 | ||
| with: | ||
| node-version: '20' | ||
|
|
||
| - name: Install Mintlify CLI | ||
| run: npm install -g mintlify | ||
|
|
||
| - name: Run Mintlify validation | ||
| run: | | ||
| echo "Running Mintlify validation checks..." | ||
| mint install || true | ||
|
Contributor
There was a problem hiding this comment. It would be good to document why you are allowing errors in |
||
|
|
||
| # Note: Mintlify Pro/Enterprise plans have automatic CI checks | ||
| # This workflow provides additional local validation | ||
|
|
||
| echo "✅ Mintlify validation completed" | ||
|
|
||
| - name: Check deployment readiness | ||
| run: | | ||
| echo "Checking if documentation is ready for deployment..." | ||
|
|
||
| # Verify docs.json exists | ||
| if [ ! -f "docs.json" ]; then | ||
| echo "❌ Error: docs.json not found" | ||
| exit 1 | ||
| fi | ||
|
|
||
| echo "✅ Documentation structure is valid" | ||
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
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
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
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.