From 3af77ba6bb160c60356b6e51059a397e2f4266b0 Mon Sep 17 00:00:00 2001 From: Danny Date: Thu, 28 Aug 2025 23:34:35 -0700 Subject: [PATCH 1/3] feat: add script to check broken links excluding api-reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add mintlify/check-links.sh script that filters out /api-reference links - Update GitHub workflow to use the new script for PR checks - Add testing instructions to CLAUDE.md - Script returns appropriate exit codes for CI/CD integration This improves the reliability of documentation link checking by excluding known false positives from api-reference paths. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .github/workflows/broken-links.yml | 79 +++--------------------------- mintlify/CLAUDE.md | 7 +++ mintlify/check-links.sh | 73 +++++++++++++++++++++++++++ 3 files changed, 87 insertions(+), 72 deletions(-) create mode 100755 mintlify/check-links.sh diff --git a/.github/workflows/broken-links.yml b/.github/workflows/broken-links.yml index 7305d12a9..ffb6ce896 100644 --- a/.github/workflows/broken-links.yml +++ b/.github/workflows/broken-links.yml @@ -5,10 +5,10 @@ on: paths: - 'mintlify/**/*.mdx' - '.github/workflows/broken-links.yml' + - 'mintlify/check-links.sh' permissions: contents: read - pull-requests: write jobs: check-broken-links: @@ -18,81 +18,16 @@ jobs: - name: Checkout repository uses: actions/checkout@v4 - - name: Setup Node.js - uses: actions/setup-node@v4 - with: - node-version: '18' - - name: Install Mintlify CLI run: npm install -g mintlify - name: Run broken links check - id: broken-links - working-directory: mintlify run: | - echo "Running mint broken-links in mintlify directory..." - - # Run broken links check and capture both stdout and stderr - set +e # Don't exit on error - mint broken-links &> broken-links-output.txt - mint_exit_code=$? - set -e # Re-enable exit on error - - echo "mint_exit_code=$mint_exit_code" >> $GITHUB_OUTPUT - - # Show original output for debugging - echo "Original mint output:" - cat broken-links-output.txt + echo "## 🔍 Checking for broken links (excluding /api-reference)..." + echo "" - # Always report success and pass through the raw output - echo "has_broken_links=false" >> $GITHUB_OUTPUT - echo "RAW_OUTPUT<> $GITHUB_OUTPUT - cat broken-links-output.txt >> $GITHUB_OUTPUT - echo "EOF" >> $GITHUB_OUTPUT + # Run the check script + ./mintlify/check-links.sh - - name: Comment on PR - uses: actions/github-script@v7 - with: - script: | - const rawOutput = `${{ steps.broken-links.outputs.RAW_OUTPUT }}`; - - const body = `## 📝 Broken Links Check Report - - > **Note**: Entries under \`/api-reference/\` are likely false positives and can be ignored. - - The following is the output from the broken links check: - - \`\`\` - ${rawOutput} - \`\`\` - `; - - // Find existing comment - const comments = await github.rest.issues.listComments({ - owner: context.repo.owner, - repo: context.repo.repo, - issue_number: context.issue.number, - }); - - const existingComment = comments.data.find(comment => - comment.user.login === 'github-actions[bot]' && - comment.body.includes('Broken Links Check') - ); - - if (existingComment) { - // Update existing comment - await github.rest.issues.updateComment({ - owner: context.repo.owner, - repo: context.repo.repo, - comment_id: existingComment.id, - body: body - }); - } else { - // Create new comment - await github.rest.issues.createComment({ - owner: context.repo.owner, - repo: context.repo.repo, - issue_number: context.issue.number, - body: body - }); - } + echo "" + echo "> **Note**: Links to \`/api-reference/\` are automatically excluded from this check." \ No newline at end of file diff --git a/mintlify/CLAUDE.md b/mintlify/CLAUDE.md index 80f6f0856..b66678905 100644 --- a/mintlify/CLAUDE.md +++ b/mintlify/CLAUDE.md @@ -33,6 +33,13 @@ mint install - Install Mintlify CLI globally: `npm i -g mint` - Run commands from the root directory where `docs.json` is located +### Testing +```bash +# Check for broken links (excluding /api-reference) +./mintlify/check-links.sh +``` +Run this test before committing any documentation changes to ensure all internal links are valid. + ## Content Management - **MDX Files**: All documentation pages use MDX format combining Markdown with React components diff --git a/mintlify/check-links.sh b/mintlify/check-links.sh new file mode 100755 index 000000000..d803ebd76 --- /dev/null +++ b/mintlify/check-links.sh @@ -0,0 +1,73 @@ +#!/bin/bash + +# Change to the mintlify directory +cd "$(dirname "$0")" + +# Run mint broken-links and capture output +echo "Checking for broken links in mintlify directory..." +output=$(mint broken-links 2>&1) + +# Check if mint command failed completely +if [ $? -ne 0 ] && [ -z "$output" ]; then + echo "Error: Failed to run 'mint broken-links' command" + exit 1 +fi + +# Check if no broken links were found at all +if echo "$output" | grep -q "No broken links found"; then + echo "✅ No broken links found" + exit 0 +fi + +# Process the output to filter out api-reference links +# First, let's identify files that ONLY have api-reference links +has_non_api_links=false +current_file="" +file_has_non_api_links=false +filtered_lines="" + +while IFS= read -r line; do + # Check if this is a file name line (ends with .mdx or .md) + if echo "$line" | grep -qE '\.(mdx?|md)$'; then + # If we had a previous file with non-api links, add it to output + if [ -n "$current_file" ] && [ "$file_has_non_api_links" = true ]; then + filtered_lines="${filtered_lines}${current_file}\n" + fi + current_file="$line" + file_has_non_api_links=false + # Check if this is a link line (contains ⎿ or →) + elif echo "$line" | grep -qE '⎿|→'; then + # Check if this link is NOT an api-reference link + if ! echo "$line" | grep -q "/api-reference"; then + file_has_non_api_links=true + has_non_api_links=true + filtered_lines="${filtered_lines}${line}\n" + fi + # Keep the summary line only if we have non-api links + elif echo "$line" | grep -q "found.*broken links"; then + continue # Skip for now, we'll add our own summary + fi +done <<< "$output" + +# Add the last file if it had non-api links +if [ -n "$current_file" ] && [ "$file_has_non_api_links" = true ]; then + filtered_lines="${filtered_lines}${current_file}\n" +fi + +# Output results +if [ "$has_non_api_links" = true ]; then + echo "❌ Broken links found (excluding /api-reference):" + echo "" + printf "$filtered_lines" + + # Count the actual broken links + link_count=$(printf "$filtered_lines" | grep -c "⎿\|→" || echo "0") + if [ $link_count -gt 0 ]; then + echo "" + echo "Total broken links (excluding /api-reference): $link_count" + fi + exit 1 +else + echo "✅ No broken links found (excluding /api-reference)" + exit 0 +fi \ No newline at end of file From 2c92b5d9cd635a0f1685f7b82114df9c300bb719 Mon Sep 17 00:00:00 2001 From: Danny Date: Thu, 28 Aug 2025 23:36:22 -0700 Subject: [PATCH 2/3] chore: update --- mintlify/concepts/data-model.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mintlify/concepts/data-model.mdx b/mintlify/concepts/data-model.mdx index e6c76af7e..958f97f0d 100644 --- a/mintlify/concepts/data-model.mdx +++ b/mintlify/concepts/data-model.mdx @@ -27,7 +27,7 @@ A `Database` is an individual database within a database instance. Each database ## Database Group -A `Database Group` contains multiple databases with similar schema structures, such as per-tenant or partitioned databases. Bytebase can apply [batch changes](/change-database/batch-change) consistently across all databases in a group. +A `Database Group` contains multiple databases with similar schema structures, such as per-tenant or partitioned databases. Bytebase can apply [batch changes](/change-database/batch-changes) consistently across all databases in a group. ## Identity and Access Management (IAM) From 9098ad76a09ec5c749d86aa071a8264d598bda4e Mon Sep 17 00:00:00 2001 From: Danny Date: Thu, 28 Aug 2025 23:37:45 -0700 Subject: [PATCH 3/3] chore: update --- mintlify/concepts/data-model.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mintlify/concepts/data-model.mdx b/mintlify/concepts/data-model.mdx index 958f97f0d..e6c76af7e 100644 --- a/mintlify/concepts/data-model.mdx +++ b/mintlify/concepts/data-model.mdx @@ -27,7 +27,7 @@ A `Database` is an individual database within a database instance. Each database ## Database Group -A `Database Group` contains multiple databases with similar schema structures, such as per-tenant or partitioned databases. Bytebase can apply [batch changes](/change-database/batch-changes) consistently across all databases in a group. +A `Database Group` contains multiple databases with similar schema structures, such as per-tenant or partitioned databases. Bytebase can apply [batch changes](/change-database/batch-change) consistently across all databases in a group. ## Identity and Access Management (IAM)