From 2c34b794265bae6860cebb28d36ff5bf10309cf9 Mon Sep 17 00:00:00 2001 From: Cordtus Date: Mon, 23 Jun 2025 13:25:07 -0600 Subject: [PATCH 1/4] add simple validation for docs.json and broken links --- .github/workflows/docs-checks.yml | 54 +++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 .github/workflows/docs-checks.yml diff --git a/.github/workflows/docs-checks.yml b/.github/workflows/docs-checks.yml new file mode 100644 index 00000000..825cef67 --- /dev/null +++ b/.github/workflows/docs-checks.yml @@ -0,0 +1,54 @@ +name: Mintlify Documentation Checks + +on: + pull_request: + branches: [ main ] + paths: + - '**.mdx' + - '**.md' + - 'docs.json' + - '**.yaml' + - '**.yml' + push: + branches: [ main ] + +jobs: + validate-docs-json: + name: Validate docs.json + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + + - name: Validate docs.json against Mintlify schema + run: | + # Install ajv-cli for JSON schema validation + npm install -g ajv-cli ajv-formats + + # Download Mintlify schema + curl -o mintlify-schema.json https://leaves.mintlify.com/schema/docs.json + + # Validate docs.json + echo "Validating docs.json against Mintlify schema..." + ajv validate -s mintlify-schema.json -d docs.json --strict=false --all-errors + + broken-links: + name: Check Broken Links + runs-on: ubuntu-latest + steps: + - 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 mint + + - name: Check for broken links + run: mint broken-links \ No newline at end of file From 57d7da371df8c6fbf7d5023ae335d91d9e016b3d Mon Sep 17 00:00:00 2001 From: Cordt Hanson <96965330+Cordtus@users.noreply.github.com> Date: Mon, 23 Jun 2025 13:40:25 -0600 Subject: [PATCH 2/4] Update docs-checks.yml Workaround for broken escaping in mintlify json schema --- .github/workflows/docs-checks.yml | 37 +++++++++++++++++++++++-------- 1 file changed, 28 insertions(+), 9 deletions(-) diff --git a/.github/workflows/docs-checks.yml b/.github/workflows/docs-checks.yml index 825cef67..6d594a03 100644 --- a/.github/workflows/docs-checks.yml +++ b/.github/workflows/docs-checks.yml @@ -18,37 +18,56 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - + - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '18' - + - name: Validate docs.json against Mintlify schema run: | # Install ajv-cli for JSON schema validation npm install -g ajv-cli ajv-formats - + # Download Mintlify schema curl -o mintlify-schema.json https://leaves.mintlify.com/schema/docs.json - + + # Fix the broken regex patterns in the schema + # The schema has invalid escapes for colons and periods in regex patterns + sed -i 's/\\\\:/:/g' mintlify-schema.json + sed -i 's/\\\\\./\\./g' mintlify-schema.json + + # Also fix the specific osano.com regex that's causing issues + sed -i 's/"pattern":"\\^https\\\\:\\\\\\/\\\\\\/cmp\\\\.osano\\\\.com\\\\\\/"/"pattern":"^https:\\/\\/cmp\\.osano\\.com\\/"/' mintlify-schema.json + # Validate docs.json echo "Validating docs.json against Mintlify schema..." - ajv validate -s mintlify-schema.json -d docs.json --strict=false --all-errors + if ajv validate -s mintlify-schema.json -d docs.json --strict=false --all-errors; then + echo "docs.json valid - OK" + else + echo "docs.json invalid" + echo "" + echo "Common issues to check:" + echo "- theme must be one of: mint, maple, palm, willow, linden, almond, aspen" + echo "- navigation structure must follow the schema" + echo "- colors must be valid hex codes" + echo "- all page references must be strings" + exit 1 + fi broken-links: name: Check Broken Links runs-on: ubuntu-latest steps: - 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 mint - + - name: Check for broken links - run: mint broken-links \ No newline at end of file + run: mint broken-links From f548cf7bb5aeec7e8633ad8984f58922853e8862 Mon Sep 17 00:00:00 2001 From: Cordt Hanson <96965330+Cordtus@users.noreply.github.com> Date: Mon, 23 Jun 2025 13:44:49 -0600 Subject: [PATCH 3/4] Update docs-checks.yml Fix delimiter breaking everything --- .github/workflows/docs-checks.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/docs-checks.yml b/.github/workflows/docs-checks.yml index 6d594a03..db9c9ba1 100644 --- a/.github/workflows/docs-checks.yml +++ b/.github/workflows/docs-checks.yml @@ -32,18 +32,18 @@ jobs: # Download Mintlify schema curl -o mintlify-schema.json https://leaves.mintlify.com/schema/docs.json - # Fix the broken regex patterns in the schema + # Fix the broken regex patterns in the schema using | as delimiter # The schema has invalid escapes for colons and periods in regex patterns - sed -i 's/\\\\:/:/g' mintlify-schema.json - sed -i 's/\\\\\./\\./g' mintlify-schema.json + sed -i 's|\\\\:|:|g' mintlify-schema.json + sed -i 's|\\\\\.|\\.|g' mintlify-schema.json # Also fix the specific osano.com regex that's causing issues - sed -i 's/"pattern":"\\^https\\\\:\\\\\\/\\\\\\/cmp\\\\.osano\\\\.com\\\\\\/"/"pattern":"^https:\\/\\/cmp\\.osano\\.com\\/"/' mintlify-schema.json + sed -i 's|"pattern":"\\^https\\\\:\\\\\\/\\\\\\/cmp\\\\.osano\\\\.com\\\\\\/"|"pattern":"^https://cmp\\.osano\\.com/"|' mintlify-schema.json # Validate docs.json echo "Validating docs.json against Mintlify schema..." if ajv validate -s mintlify-schema.json -d docs.json --strict=false --all-errors; then - echo "docs.json valid - OK" + echo "docs.json valid - OK!" else echo "docs.json invalid" echo "" From bc5308f0290724d29a95f1c6235242e346970275 Mon Sep 17 00:00:00 2001 From: Cordt Hanson <96965330+Cordtus@users.noreply.github.com> Date: Mon, 23 Jun 2025 13:50:26 -0600 Subject: [PATCH 4/4] Update docs-checks.yml Use generic validation to avoid issues with mintlify json schema --- .github/workflows/docs-checks.yml | 102 ++++++++++++++++++++++-------- 1 file changed, 77 insertions(+), 25 deletions(-) diff --git a/.github/workflows/docs-checks.yml b/.github/workflows/docs-checks.yml index db9c9ba1..c6e2d895 100644 --- a/.github/workflows/docs-checks.yml +++ b/.github/workflows/docs-checks.yml @@ -24,36 +24,88 @@ jobs: with: node-version: '18' - - name: Validate docs.json against Mintlify schema + - name: Validate docs.json structure run: | - # Install ajv-cli for JSON schema validation - npm install -g ajv-cli ajv-formats + # First, validate it's valid JSON + echo "Checking if docs.json is valid JSON..." + cat docs.json | jq empty || (echo "docs.json is not valid JSON" && exit 1) - # Download Mintlify schema - curl -o mintlify-schema.json https://leaves.mintlify.com/schema/docs.json + # Now validate the Mintlify-specific structure + echo "Validating Mintlify structure..." + node -e " + const fs = require('fs'); + const docs = JSON.parse(fs.readFileSync('docs.json', 'utf8')); + const errors = []; - # Fix the broken regex patterns in the schema using | as delimiter - # The schema has invalid escapes for colons and periods in regex patterns - sed -i 's|\\\\:|:|g' mintlify-schema.json - sed -i 's|\\\\\.|\\.|g' mintlify-schema.json + // Check required top-level fields + const required = ['name', 'theme', 'colors', 'navigation']; + required.forEach(field => { + if (!docs[field]) errors.push(\`Missing required field: \${field}\`); + }); - # Also fix the specific osano.com regex that's causing issues - sed -i 's|"pattern":"\\^https\\\\:\\\\\\/\\\\\\/cmp\\\\.osano\\\\.com\\\\\\/"|"pattern":"^https://cmp\\.osano\\.com/"|' mintlify-schema.json + // Validate theme + const validThemes = ['mint', 'maple', 'palm', 'willow', 'linden', 'almond', 'aspen']; + if (docs.theme && !validThemes.includes(docs.theme)) { + errors.push(\`Invalid theme '\${docs.theme}'. Must be one of: \${validThemes.join(', ')}\`); + } - # Validate docs.json - echo "Validating docs.json against Mintlify schema..." - if ajv validate -s mintlify-schema.json -d docs.json --strict=false --all-errors; then - echo "docs.json valid - OK!" - else - echo "docs.json invalid" - echo "" - echo "Common issues to check:" - echo "- theme must be one of: mint, maple, palm, willow, linden, almond, aspen" - echo "- navigation structure must follow the schema" - echo "- colors must be valid hex codes" - echo "- all page references must be strings" - exit 1 - fi + // Validate colors + if (docs.colors) { + const hexRegex = /^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/; + if (!docs.colors.primary) errors.push('Missing required color: primary'); + + Object.entries(docs.colors).forEach(([name, color]) => { + if (!hexRegex.test(color)) { + errors.push(\`Invalid \${name} color '\${color}'. Must be a valid hex code.\`); + } + }); + } + + // Validate navigation structure + if (docs.navigation) { + if (docs.navigation.tabs) { + docs.navigation.tabs.forEach((tab, i) => { + if (!tab.tab) errors.push(\`navigation.tabs[\${i}] missing required field: tab\`); + + // Check for either pages or groups + if (!tab.pages && !tab.groups) { + errors.push(\`navigation.tabs[\${i}] must have either 'pages' or 'groups'\`); + } + + // Validate groups if present + if (tab.groups) { + tab.groups.forEach((group, j) => { + if (!group.group) { + errors.push(\`navigation.tabs[\${i}].groups[\${j}] missing required field: group\`); + } + if (!group.pages || !Array.isArray(group.pages)) { + errors.push(\`navigation.tabs[\${i}].groups[\${j}] missing required field: pages (array)\`); + } + }); + } + }); + } else if (!docs.navigation.pages && !docs.navigation.groups) { + errors.push('navigation must have tabs, pages, or groups'); + } + } + + // Validate icon library if specified + if (docs.icons?.library) { + const validLibraries = ['fontawesome', 'lucide']; + if (!validLibraries.includes(docs.icons.library)) { + errors.push(\`Invalid icon library '\${docs.icons.library}'. Must be: \${validLibraries.join(' or ')}\`); + } + } + + // Output results + if (errors.length > 0) { + console.error('invalid docs.json:'); + errors.forEach(err => console.error(' - ' + err)); + process.exit(1); + } else { + console.log('docs.json valid - OK!'); + } + " broken-links: name: Check Broken Links