From 72769dfef05936e397c387cf7ba5ced68f0b2c5e Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Thu, 22 Jan 2026 20:37:32 +0100 Subject: [PATCH] ci: Cleanup validation --- .github/workflows/docs-validation.yml | 29 +---- .github/workflows/mintlify-ci.yml | 44 -------- README.md | 52 +-------- scripts/validate-docs.sh | 157 -------------------------- 4 files changed, 11 insertions(+), 271 deletions(-) delete mode 100644 .github/workflows/mintlify-ci.yml delete mode 100755 scripts/validate-docs.sh diff --git a/.github/workflows/docs-validation.yml b/.github/workflows/docs-validation.yml index b5fc97547..77de152ee 100644 --- a/.github/workflows/docs-validation.yml +++ b/.github/workflows/docs-validation.yml @@ -1,43 +1,24 @@ 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 + name: Check for broken links runs-on: ubuntu-latest - + steps: - name: Checkout repository uses: actions/checkout@v5 - with: - fetch-depth: 0 - name: Setup Node.js uses: actions/setup-node@v6 with: - node-version: '22' - - - name: Install jq - run: sudo apt-get update && sudo apt-get install -y jq + node-version: "24" - - name: Run validation script - id: validate - run: | - echo "## 📚 Documentation Validation" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "Running validation checks using ./scripts/validate-docs.sh" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - - # Make script executable and run it - chmod +x ./scripts/validate-docs.sh - ./scripts/validate-docs.sh + - name: Check for broken links + run: npx mintlify broken-links diff --git a/.github/workflows/mintlify-ci.yml b/.github/workflows/mintlify-ci.yml deleted file mode 100644 index c22e2b9ae..000000000 --- a/.github/workflows/mintlify-ci.yml +++ /dev/null @@ -1,44 +0,0 @@ -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: Run Mintlify validation - run: | - echo "Running Mintlify validation checks..." - # Note: Mintlify Pro/Enterprise plans have automatic CI checks - # This workflow provides additional local validation using npx - 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" diff --git a/README.md b/README.md index 403e9b61f..5a3625491 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,8 @@ # Celo Documentation -Official documentation for Celo, built with [Mintlify](https://mintlify.com). +Official documentation for Celo -## 🔍 Documentation Validation - -We have automated checks for errors and broken links that run on every push and pull request. - -### Quick Validation - -Before committing, run local validation: - -```bash -# Run all validation checks -./scripts/validate-docs.sh - -# Check for broken links using Mintlify CLI -mint broken-links -``` - -### CI/CD Workflows - -- ✅ **Broken Links Check** - Automatically scans for broken internal/external links -- ✅ **Structure Validation** - Validates docs.json syntax and structure -- ✅ **MDX File Verification** - Ensures all referenced files exist -- ✅ **Syntax Checking** - Detects common MDX/JSX syntax errors -- ✅ **PR Comments** - Automatically comments on PRs with validation results - -Run `./scripts/validate-docs.sh` to check for errors before committing. - -## Development +## Making Changes Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally: @@ -36,25 +10,17 @@ Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your d npm i -g mint ``` -Run the following command at the root of your documentation, where your `docs.json` is located: +Run the following command. It will display a preview of you changes at `http://localhost:3000`. -```bash +```sh mint dev ``` -View your local preview at `http://localhost:3000`. - -## Publishing changes - -Install our GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app) to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch. - -**Important:** All PRs must pass validation checks before merging. - ## Contributing 1. **Before committing:** - - Run `./scripts/validate-docs.sh` to check for errors - Test your changes locally with `mint dev` + - Check for broken links with `mint broken-links` - Ensure all links work correctly 2. **Creating a PR:** @@ -67,8 +33,6 @@ Install our GitHub app from your [dashboard](https://dashboard.mintlify.com/sett - Review any warnings in PR comments - Verify changes render correctly -## Need help? - ### Troubleshooting - **Dev environment not running:** Run `mint update` to ensure you have the most recent version of the CLI @@ -79,9 +43,5 @@ Install our GitHub app from your [dashboard](https://dashboard.mintlify.com/sett ### Resources - [Celo Documentation](https://docs.celo.org) -- [Validation Script](./scripts/validate-docs.sh) -- [Mintlify Documentation](https://mintlify.com/docs) -- [Mintlify Community](https://mintlify.com/community) - [Celo Discord](https://discord.com/invite/celo) -- [Mintlify documentation](https://mintlify.com/docs) -- [Mintlify community](https://mintlify.com/community) +- [Mintlify Documentation](https://mintlify.com/docs) diff --git a/scripts/validate-docs.sh b/scripts/validate-docs.sh deleted file mode 100755 index d7a1dc2eb..000000000 --- a/scripts/validate-docs.sh +++ /dev/null @@ -1,157 +0,0 @@ -#!/bin/bash - -# Documentation Validation Script -# Run this locally before committing changes to catch issues early - -set -e - -echo "🔍 Celo Documentation Validation Script" -echo "========================================" -echo "" - -# Colors for output -RED='\033[0;31m' -GREEN='\033[0;32m' -YELLOW='\033[1;33m' -NC='\033[0m' # No Color - -# Track overall success -ALL_PASSED=true - -# Check if npx is available (for running mintlify) -echo "Checking for npx..." -if ! command -v npx &> /dev/null; then - echo -e "${RED}❌ npx is not available${NC}" - echo "Please ensure Node.js and npm are installed" - exit 1 -fi -echo -e "${GREEN}✅ npx found (will use npx mintlify)${NC}" -echo "" - -# Check if jq is installed -echo "Checking for jq..." -if ! command -v jq &> /dev/null; then - echo -e "${YELLOW}⚠️ jq is not installed (optional, for JSON validation)${NC}" - echo "Install it with: brew install jq (macOS) or apt-get install jq (Linux)" - JQ_AVAILABLE=false -else - echo -e "${GREEN}✅ jq found${NC}" - JQ_AVAILABLE=true -fi -echo "" - -# Validate docs.json -echo "1️⃣ Validating docs.json..." -if [ ! -f "docs.json" ]; then - echo -e "${RED}❌ docs.json not found!${NC}" - ALL_PASSED=false -else - if [ "$JQ_AVAILABLE" = true ]; then - if jq empty docs.json 2>&1; then - echo -e "${GREEN}✅ docs.json is valid JSON${NC}" - - # Check for required fields - if jq -e '.name' docs.json > /dev/null 2>&1; then - echo -e "${GREEN}✅ Required 'name' field present${NC}" - else - echo -e "${RED}❌ Missing required 'name' field${NC}" - ALL_PASSED=false - fi - else - echo -e "${RED}❌ docs.json has invalid JSON syntax${NC}" - ALL_PASSED=false - fi - else - echo -e "${YELLOW}⚠️ Skipping JSON validation (jq not available)${NC}" - fi -fi -echo "" - -# Check for broken links -echo "2️⃣ Checking for broken links..." -# Capture output and check for "found" message -# Temporarily disable exit on error to capture output even if command fails -set +e -BROKEN_LINKS_OUTPUT=$(npx mintlify broken-links 2>&1) -BROKEN_LINKS_EXIT_CODE=$? -set -e - -echo "$BROKEN_LINKS_OUTPUT" - -if [ $BROKEN_LINKS_EXIT_CODE -ne 0 ] || echo "$BROKEN_LINKS_OUTPUT" | grep -q "found [1-9][0-9]* broken link"; then - echo -e "${RED}❌ Broken links detected! See output above.${NC}" - ALL_PASSED=false -elif echo "$BROKEN_LINKS_OUTPUT" | grep -q "found 0 broken links"; then - echo -e "${GREEN}✅ No broken links found!${NC}" -else - echo -e "${GREEN}✅ No broken links found!${NC}" -fi -echo "" - -# Check for missing MDX files -echo "3️⃣ Checking for missing MDX files..." -if [ "$JQ_AVAILABLE" = true ]; then - MISSING_FILES=0 - - # Extract all page references and check if files exist - # Using process substitution to avoid subshell variable scope issues - while read -r page; do - file_path="${page}.mdx" - - if [ ! -f "$file_path" ] && [ ! -f "${page}.md" ]; then - echo -e "${YELLOW}⚠️ Missing file: $file_path${NC}" - MISSING_FILES=$((MISSING_FILES + 1)) - fi - done < <(jq -r '.. | .pages? // empty | .[] | select(type == "string")' docs.json 2>/dev/null) - - if [ $MISSING_FILES -eq 0 ]; then - echo -e "${GREEN}✅ All referenced MDX files exist${NC}" - else - echo -e "${YELLOW}⚠️ Some referenced files are missing${NC}" - fi -else - echo -e "${YELLOW}⚠️ Skipping MDX file check (jq not available)${NC}" -fi -echo "" - -# Check for common syntax issues -echo "4️⃣ Checking for common MDX syntax issues..." -SYNTAX_ISSUES=0 - -# Find all MDX files (excluding hidden directories and node_modules) -while IFS= read -r file; do - # Skip if in node_modules or hidden directories - if [[ "$file" == *"node_modules"* ]] || [[ "$file" == *"/.git/"* ]] || [[ "$file" == *"/_deprecated/"* ]]; then - continue - fi - - # Check for obvious syntax errors (self-closing tags that are malformed) - # Look for tags like or /> - if grep -E '<[A-Z][a-zA-Z]*\s+[^>]*$' "$file" | grep -v '>' > /dev/null 2>&1; then - # Only flag if the line truly doesn't have a closing bracket - if grep -E '<[A-Z][a-zA-Z]*\s+[a-zA-Z]+=' "$file" | grep -vE '(>|/>)\s*$' > /dev/null 2>&1; then - echo -e "${YELLOW}⚠️ Potential syntax issue in: $file${NC}" - SYNTAX_ISSUES=$((SYNTAX_ISSUES + 1)) - fi - fi -done < <(find . -type f \( -name "*.mdx" -o -name "*.md" \) 2>/dev/null) - -if [ $SYNTAX_ISSUES -eq 0 ]; then - echo -e "${GREEN}✅ No obvious syntax issues detected${NC}" -else - echo -e "${YELLOW}⚠️ Found $SYNTAX_ISSUES potential syntax issue(s)${NC}" - echo " (Note: Multi-line JSX components are properly handled)" -fi -echo "" - -# Summary -echo "========================================" -echo "📊 Summary" -echo "========================================" -if [ "$ALL_PASSED" = true ]; then - echo -e "${GREEN}🎉 All checks passed! Your documentation looks good.${NC}" - exit 0 -else - echo -e "${RED}⚠️ Some checks failed. Please fix the issues above before committing.${NC}" - exit 1 -fi