Skip to content

Commit 4b37d8c

Browse files
viral-sanganiviral-sangani
committed
ci: add GitHub workflows for documentation validation and Mintlify checks
1 parent 0827abb commit 4b37d8c

File tree

49 files changed

+558
-118
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

49 files changed

+558
-118
lines changed

‎.github/workflows/docs-validation.yml‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
name: Documentation Validation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- master
8+
pull_request:
9+
branches:
10+
- main
11+
- master
12+
workflow_dispatch:
13+
14+
jobs:
15+
validate-docs:
16+
name: Check for Errors and Broken Links
17+
runs-on: ubuntu-latest
18+
19+
steps:
20+
- name: Checkout repository
21+
uses: actions/checkout@v4
22+
with:
23+
fetch-depth: 0
24+
25+
- name: Setup Node.js
26+
uses: actions/setup-node@v4
27+
with:
28+
node-version: '20'
29+
cache: 'npm'
30+
31+
- name: Install Mintlify CLI
32+
run: npm install -g mintlify
33+
34+
- name: Check for broken links
35+
id: broken-links
36+
continue-on-error: true
37+
run: |
38+
echo "## 🔍 Broken Links Check" >> $GITHUB_STEP_SUMMARY
39+
echo "" >> $GITHUB_STEP_SUMMARY
40+
if mint broken-links 2>&1 | tee broken-links-output.txt; then
41+
echo "✅ No broken links found!" >> $GITHUB_STEP_SUMMARY
42+
else
43+
echo "❌ Broken links detected:" >> $GITHUB_STEP_SUMMARY
44+
echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
45+
cat broken-links-output.txt >> $GITHUB_STEP_SUMMARY
46+
echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
47+
exit 1
48+
fi
49+
50+
- name: Validate documentation structure
51+
id: validate-structure
52+
continue-on-error: true
53+
run: |
54+
echo "## 📋 Documentation Structure Check" >> $GITHUB_STEP_SUMMARY
55+
echo "" >> $GITHUB_STEP_SUMMARY
56+
57+
# Check if docs.json exists
58+
if [ ! -f "docs.json" ]; then
59+
echo "❌ docs.json not found!" >> $GITHUB_STEP_SUMMARY
60+
exit 1
61+
fi
62+
63+
# Validate JSON syntax
64+
if jq empty docs.json 2>&1; then
65+
echo "✅ docs.json is valid JSON" >> $GITHUB_STEP_SUMMARY
66+
else
67+
echo "❌ docs.json has invalid JSON syntax" >> $GITHUB_STEP_SUMMARY
68+
exit 1
69+
fi
70+
71+
# Check for required fields
72+
if jq -e '.name' docs.json > /dev/null; then
73+
echo "✅ Required 'name' field present" >> $GITHUB_STEP_SUMMARY
74+
else
75+
echo "❌ Missing required 'name' field" >> $GITHUB_STEP_SUMMARY
76+
exit 1
77+
fi
78+
79+
- name: Check for missing MDX files
80+
id: check-mdx
81+
continue-on-error: true
82+
run: |
83+
echo "## 📄 MDX Files Check" >> $GITHUB_STEP_SUMMARY
84+
echo "" >> $GITHUB_STEP_SUMMARY
85+
86+
# Extract all page references from docs.json and check if files exist
87+
missing_files=0
88+
89+
# Find all .mdx references in navigation
90+
jq -r '.. | .pages? // empty | .[] | select(type == "string")' docs.json | while read -r page; do
91+
# Convert page path to file path
92+
file_path="${page}.mdx"
93+
94+
if [ ! -f "$file_path" ] && [ ! -f "${page}.md" ]; then
95+
echo "⚠️ Missing file: $file_path" >> $GITHUB_STEP_SUMMARY
96+
missing_files=$((missing_files + 1))
97+
fi
98+
done
99+
100+
if [ $missing_files -eq 0 ]; then
101+
echo "✅ All referenced MDX files exist" >> $GITHUB_STEP_SUMMARY
102+
else
103+
echo "❌ Found $missing_files missing file(s)" >> $GITHUB_STEP_SUMMARY
104+
exit 1
105+
fi
106+
107+
- name: Check for common MDX syntax errors
108+
id: check-syntax
109+
continue-on-error: true
110+
run: |
111+
echo "## ⚙️ MDX Syntax Check" >> $GITHUB_STEP_SUMMARY
112+
echo "" >> $GITHUB_STEP_SUMMARY
113+
114+
errors=0
115+
116+
# Find all MDX files
117+
find . -name "*.mdx" -o -name "*.md" | while read -r file; do
118+
# Skip node_modules and hidden directories
119+
if [[ "$file" == *"node_modules"* ]] || [[ "$file" == *"/.git/"* ]]; then
120+
continue
121+
fi
122+
123+
# Check for unclosed JSX tags (basic check)
124+
if grep -E '<[A-Z][a-zA-Z]*[^/>]*$' "$file" > /dev/null 2>&1; then
125+
echo "⚠️ Potential unclosed JSX tag in: $file" >> $GITHUB_STEP_SUMMARY
126+
errors=$((errors + 1))
127+
fi
128+
done
129+
130+
if [ $errors -eq 0 ]; then
131+
echo "✅ No obvious syntax errors detected" >> $GITHUB_STEP_SUMMARY
132+
else
133+
echo "⚠️ Found $errors potential syntax issue(s)" >> $GITHUB_STEP_SUMMARY
134+
fi
135+
136+
- name: Final status check
137+
if: always()
138+
run: |
139+
echo "## 🎯 Summary" >> $GITHUB_STEP_SUMMARY
140+
echo "" >> $GITHUB_STEP_SUMMARY
141+
142+
all_passed=true
143+
144+
if [ "${{ steps.broken-links.outcome }}" != "success" ]; then
145+
echo "- ❌ Broken links check failed" >> $GITHUB_STEP_SUMMARY
146+
all_passed=false
147+
else
148+
echo "- ✅ Broken links check passed" >> $GITHUB_STEP_SUMMARY
149+
fi
150+
151+
if [ "${{ steps.validate-structure.outcome }}" != "success" ]; then
152+
echo "- ❌ Structure validation failed" >> $GITHUB_STEP_SUMMARY
153+
all_passed=false
154+
else
155+
echo "- ✅ Structure validation passed" >> $GITHUB_STEP_SUMMARY
156+
fi
157+
158+
if [ "${{ steps.check-mdx.outcome }}" != "success" ]; then
159+
echo "- ❌ MDX files check failed" >> $GITHUB_STEP_SUMMARY
160+
all_passed=false
161+
else
162+
echo "- ✅ MDX files check passed" >> $GITHUB_STEP_SUMMARY
163+
fi
164+
165+
if [ "$all_passed" = false ]; then
166+
echo "" >> $GITHUB_STEP_SUMMARY
167+
echo "⚠️ Some checks failed. Please review the errors above." >> $GITHUB_STEP_SUMMARY
168+
exit 1
169+
else
170+
echo "" >> $GITHUB_STEP_SUMMARY
171+
echo "🎉 All documentation checks passed successfully!" >> $GITHUB_STEP_SUMMARY
172+
fi
173+
174+
- name: Comment PR with results
175+
if: github.event_name == 'pull_request' && always()
176+
uses: actions/github-script@v7
177+
with:
178+
script: |
179+
const fs = require('fs');
180+
181+
let comment = '## 📚 Documentation Validation Results\n\n';
182+
183+
// Add check results
184+
comment += '### Check Status\n\n';
185+
comment += '| Check | Status |\n';
186+
comment += '|-------|--------|\n';
187+
comment += `| Broken Links | ${'${{ steps.broken-links.outcome }}' === 'success' ? '✅ Passed' : '❌ Failed'} |\n`;
188+
comment += `| Structure | ${'${{ steps.validate-structure.outcome }}' === 'success' ? '✅ Passed' : '❌ Failed'} |\n`;
189+
comment += `| MDX Files | ${'${{ steps.check-mdx.outcome }}' === 'success' ? '✅ Passed' : '❌ Failed'} |\n`;
190+
comment += `| Syntax | ${'${{ steps.check-syntax.outcome }}' === 'success' ? '✅ Passed' : '⚠️ Warnings'} |\n`;
191+
192+
// Add broken links details if available
193+
if (fs.existsSync('broken-links-output.txt')) {
194+
const brokenLinks = fs.readFileSync('broken-links-output.txt', 'utf8');
195+
if (brokenLinks.trim()) {
196+
comment += '\n### Broken Links Details\n\n```\n' + brokenLinks + '\n```\n';
197+
}
198+
}
199+
200+
comment += '\n---\n';
201+
comment += '*This check was performed by the [Documentation Validation](.github/workflows/docs-validation.yml) workflow.*';
202+
203+
github.rest.issues.createComment({
204+
issue_number: context.issue.number,
205+
owner: context.repo.owner,
206+
repo: context.repo.repo,
207+
body: comment
208+
});

‎.github/workflows/mintlify-ci.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: Mintlify CI Checks
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- master
8+
pull_request:
9+
branches:
10+
- main
11+
- master
12+
13+
jobs:
14+
mintlify-checks:
15+
name: Run Mintlify CI Checks
16+
runs-on: ubuntu-latest
17+
18+
steps:
19+
- name: Checkout repository
20+
uses: actions/checkout@v4
21+
22+
- name: Setup Node.js
23+
uses: actions/setup-node@v4
24+
with:
25+
node-version: '20'
26+
27+
- name: Install Mintlify CLI
28+
run: npm install -g mintlify
29+
30+
- name: Run Mintlify validation
31+
run: |
32+
echo "Running Mintlify validation checks..."
33+
mint install || true
34+
35+
# Note: Mintlify Pro/Enterprise plans have automatic CI checks
36+
# This workflow provides additional local validation
37+
38+
echo "✅ Mintlify validation completed"
39+
40+
- name: Check deployment readiness
41+
run: |
42+
echo "Checking if documentation is ready for deployment..."
43+
44+
# Verify docs.json exists
45+
if [ ! -f "docs.json" ]; then
46+
echo "❌ Error: docs.json not found"
47+
exit 1
48+
fi
49+
50+
echo "✅ Documentation structure is valid"

‎README.md‎

Lines changed: 57 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,44 @@
1-
# Mintlify Starter Kit
1+
# Celo Documentation
22

3-
Use the starter kit to get your docs deployed and ready to customize.
3+
Official documentation for Celo, built with [Mintlify](https://mintlify.com).
44

5-
Click the green **Use this template** button at the top of this repo to copy the Mintlify starter kit. The starter kit contains examples with
5+
## 🔍 Documentation Validation
66

7-
- Guide pages
8-
- Navigation
9-
- Customizations
10-
- API reference pages
11-
- Use of popular components
7+
We have automated checks for errors and broken links that run on every push and pull request.
128

13-
**[Follow the full quickstart guide](https://starter.mintlify.com/quickstart)**
9+
### Quick Validation
1410

15-
## Development
11+
Before committing, run local validation:
1612

17-
Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally. To install, use the following command:
13+
```bash
14+
# Run all validation checks
15+
./scripts/validate-docs.sh
1816

17+
# Check for broken links using Mintlify CLI
18+
mint broken-links
1919
```
20-
npm i -g mint
20+
21+
### CI/CD Workflows
22+
23+
- ✅ **Broken Links Check** - Automatically scans for broken internal/external links
24+
- ✅ **Structure Validation** - Validates docs.json syntax and structure
25+
- ✅ **MDX File Verification** - Ensures all referenced files exist
26+
- ✅ **Syntax Checking** - Detects common MDX/JSX syntax errors
27+
- ✅ **PR Comments** - Automatically comments on PRs with validation results
28+
29+
See [DOCS_VALIDATION.md](./DOCS_VALIDATION.md) for complete documentation validation guide.
30+
31+
## Development
32+
33+
Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally:
34+
35+
```bash
36+
npm i -g mintlify
2137
```
2238

2339
Run the following command at the root of your documentation, where your `docs.json` is located:
2440

25-
```
41+
```bash
2642
mint dev
2743
```
2844

@@ -32,13 +48,37 @@ View your local preview at `http://localhost:3000`.
3248

3349
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.
3450

51+
**Important:** All PRs must pass validation checks before merging.
52+
53+
## Contributing
54+
55+
1. **Before committing:**
56+
- Run `./scripts/validate-docs.sh` to check for errors
57+
- Test your changes locally with `mint dev`
58+
- Ensure all links work correctly
59+
60+
2. **Creating a PR:**
61+
- Wait for automated checks to complete
62+
- Review any validation warnings or errors
63+
- Fix issues before requesting review
64+
65+
3. **For reviewers:**
66+
- Check that all validation checks pass
67+
- Review any warnings in PR comments
68+
- Verify changes render correctly
69+
3570
## Need help?
3671

3772
### Troubleshooting
3873

39-
- If your dev environment isn't running: Run `mint update` to ensure you have the most recent version of the CLI.
40-
- If a page loads as a 404: Make sure you are running in a folder with a valid `docs.json`.
74+
- **Dev environment not running:** Run `mint update` to ensure you have the most recent version of the CLI
75+
- **Page loads as 404:** Make sure you are running in a folder with a valid `docs.json`
76+
- **Validation fails:** Check [DOCS_VALIDATION.md](./DOCS_VALIDATION.md) for detailed troubleshooting
77+
- **Broken links detected:** Review the validation output and fix referenced files or URLs
4178

4279
### Resources
43-
- [Mintlify documentation](https://mintlify.com/docs)
44-
- [Mintlify community](https://mintlify.com/community)
80+
- [Celo Documentation](https://docs.celo.org)
81+
- [Documentation Validation Guide](./DOCS_VALIDATION.md)
82+
- [Mintlify Documentation](https://mintlify.com/docs)
83+
- [Mintlify Community](https://mintlify.com/community)
84+
- [Celo Discord](https://discord.com/invite/celo)

‎_deprecated/cel2/faq.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -77,12 +77,12 @@ There are multiple options.
7777

7878
### How is the Celo L2 different to Optimism?
7979

80-
See [What's Changed Optimism -> Celo L2](./whats-changed/op-l2).
80+
See [What's Changed Optimism -> Celo L2](/legacy/transition/optimism/op-l2).
8181
Also see [Celo L2 Specification](https://specs.celo.org/root.html) for greater detail.
8282

8383
### What are the costs for L1 data and how are they paid?
8484

85-
See [What's changed section covering L1 fees](/cel2/whats-changed/op-l2#l1-fees).
85+
See [What's changed section covering L1 fees](/legacy/transition/optimism/op-l2#l1-fees).
8686

8787
### What's the block time?
8888

@@ -94,7 +94,7 @@ The gas limit per block is 30 million, so the maximum throughput is 30M gas/s.
9494

9595
### Is there anything that used to work on Celo L1 that doesn’t anymore on L2?
9696

97-
See [What's Changed Celo L1 -> L2](/cel2/whats-changed/l1-l2.md) and [L1 -> L2 Migration Changes](https://specs.celo.org/l2_migration.html) in the spec for greater detail.
97+
See [What's Changed Celo L1 -> L2](/legacy/transition/whats-changed/l1-l2) and [L1 -> L2 Migration Changes](https://specs.celo.org/l2_migration.html) in the spec for greater detail.
9898

9999
## Testnets
100100

‎_deprecated/integration/listings.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ For more specific use-cases for exchanges, please checkout the [Custody and Exch
4141

4242
### Celo Native Asset and Stable Value Currencies
4343

44-
There are key assets on the Celo network, the Celo native asset (CELO) and Celo-powered Stable Value Currencies, such as Celo Dollar (cUSD) and Celo Euro (cEUR). CELO was formerly called Celo Gold (cGLD) when the contract was deployed, so you will often see references to Celo Gold and CGLD in the codebase. To learn more about the two, please read [this](/developer/migrate/from-ethereum#the-celo-native-asset-and-the-celo-dollar) section of the docs.
44+
There are key assets on the Celo network, the Celo native asset (CELO) and Celo-powered Stable Value Currencies, such as Celo Dollar (cUSD) and Celo Euro (cEUR). CELO was formerly called Celo Gold (cGLD) when the contract was deployed, so you will often see references to Celo Gold and CGLD in the codebase. To learn more about the two, please read [this](/tooling/overview/migrate/from-ethereum#the-celo-native-asset-and-the-celo-dollar) section of the docs.
4545

4646
You can also view the forum post about the name change [here](https://forum.celo.org/t/proposal-to-rename-celo-gold-to-celo-native-asset/528).
4747

0 commit comments

Comments
 (0)