feat(docs-migration): second iteration of docs migration #5056
Conversation
![propel-code-bot[bot]](https://avatars.githubusercontent.com/in/1179004?s=60&v=4){kind=small}
| } | ||
| let connectMdxPath: string | null = null; | ||
| if (provider.docs_connect) { | ||
| const updatedConnectMdx = path.join(updatedDocsPath, `${providerKey}/connect.mdx`); | ||
| if (!fs.existsSync(connectMdx) && !fs.existsSync(updatedConnectMdx)) { | ||
| const connectMdxExists = fs.existsSync(connectMdx); | ||
| const updatedConnectMdxExists = fs.existsSync(updatedConnectMdx); | ||
| if (!connectMdxExists && !updatedConnectMdxExists) { |
There was a problem hiding this comment.
[BestPractice]
Missing validation for provider configuration changes
The providers.yaml file is being updated with new docs and setup_guide_url fields, but there's no validation in validate.ts to ensure these URLs are valid or that the documentation files actually exist.
Issue: When setup_guide_url is added (e.g., for accelo), the system doesn't verify:
- The URL format is valid
- The referenced documentation file exists
- The URL is accessible
Recommendation: Add validation in validate.ts:
if (provider.setup_guide_url) {
// Validate URL format
try {
new URL(provider.setup_guide_url);
} catch {
console.error(chalk.red('error'), chalk.blue(providerKey), `Invalid setup_guide_url format`);
error = true;
}
// Check if local doc file exists
const docPath = provider.setup_guide_url.replace('https://nango.dev/docs/', '');
const fullPath = path.join(docsPath, `${docPath}.mdx`);
if (!fs.existsSync(fullPath)) {
console.error(chalk.red('error'), chalk.blue(providerKey), `setup_guide_url references non-existent file: ${fullPath}`);
error = true;
}
}Context for Agents
**Missing validation for provider configuration changes**
The `providers.yaml` file is being updated with new `docs` and `setup_guide_url` fields, but there's no validation in `validate.ts` to ensure these URLs are valid or that the documentation files actually exist.
**Issue:** When `setup_guide_url` is added (e.g., for `accelo`), the system doesn't verify:
1. The URL format is valid
2. The referenced documentation file exists
3. The URL is accessible
**Recommendation:** Add validation in `validate.ts`:
```typescript
if (provider.setup_guide_url) {
// Validate URL format
try {
new URL(provider.setup_guide_url);
} catch {
console.error(chalk.red('error'), chalk.blue(providerKey), `Invalid setup_guide_url format`);
error = true;
}
// Check if local doc file exists
const docPath = provider.setup_guide_url.replace('https://nango.dev/docs/', '');
const fullPath = path.join(docsPath, `${docPath}.mdx`);
if (!fs.existsSync(fullPath)) {
console.error(chalk.red('error'), chalk.blue(providerKey), `setup_guide_url references non-existent file: ${fullPath}`);
error = true;
}
}
```
File: scripts/validation/providers/validate.ts
Line: 133| @@ -0,0 +1,85 @@ | |||
| --- | |||
| title: 'Quickbooks Sandbox' | |||
There was a problem hiding this comment.
[Documentation]
Correct capitalization: 'Quickbooks Sandbox' should be 'QuickBooks Sandbox'.
Additional affected locations:
- docs/api-integrations/quickbooks.mdx:2
Context for Agents
[**Documentation**]
Correct capitalization: 'Quickbooks Sandbox' should be 'QuickBooks Sandbox'.
**Additional affected locations:**
- docs/api-integrations/quickbooks.mdx:2
File: docs/api-integrations/quickbooks-sandbox.mdx
Line: 2
| } | ||
| }); | ||
| console.log(JSON.stringify(res.data, 2, null)); | ||
| ``` |
There was a problem hiding this comment.
[Documentation]
Fix the code sample: JSON.stringify expects the replacer as the second argument and the spacing value as the third. Update the call to JSON.stringify(res.data, null, 2) so readers don’t hit a runtime error when copying the snippet.
Context for Agents
[**Documentation**]
Fix the code sample: `JSON.stringify` expects the replacer as the second argument and the spacing value as the third. Update the call to `JSON.stringify(res.data, null, 2)` so readers don’t hit a runtime error when copying the snippet.
File: docs/api-integrations/attio.mdx
Line: 52| }); | ||
|
|
||
| console.log(JSON.stringify(res.data, 2, null)); | ||
| ``` |
There was a problem hiding this comment.
[Documentation]
Update the code example to call JSON.stringify(res.data, null, 2) — the current argument order passes a number as the replacer, which will throw when readers run the snippet.
Context for Agents
[**Documentation**]
Update the code example to call `JSON.stringify(res.data, null, 2)` — the current argument order passes a number as the replacer, which will throw when readers run the snippet.
File: docs/api-integrations/linear.mdx
Line: 55
docs/api-integrations/github-app/how-to-register-your-own-github-app-api-app.mdx
Show resolved
Hide resolved
🤖 My Senior Dev — Analysis Complete👤 For @khaliqgant🎯 Unknown (0% confidence) • 📁 Expert in View your contributor analytics → 📊 196 files reviewed • 3 high risk • 2 need attention 🚨 High Risk:
🚀 Open Interactive Review →The full interface unlocks features not available in GitHub:
💬 Engage Right from GitHubQuick try:
📖 View all 12 personas & slash commandsYou can interact with me by mentioning In PR comments or on any line of code:
Slash commands:
AI Personas (mention to get their perspective):
For the best experience, view this PR on myseniordev.com — includes AI chat, file annotations, and interactive reviews. |
| import { Nango } from '@nangohq/node'; | ||
|
|
||
| const nango = new Nango({ secretKey: '<NANGO-SECRET-KEY>' }); | ||
|
|
There was a problem hiding this comment.
[Documentation] The anchor here includes the emoji character, but the generated heading ID strips emojis, so this link does not resolve. Please adjust it to point to the actual heading ID (for example #-clickup-integration-guides).
Context for Agents
[**Documentation**]
The anchor here includes the emoji character, but the generated heading ID strips emojis, so this link does not resolve. Please adjust it to point to the actual heading ID (for example `#-clickup-integration-guides`).
File: docs/api-integrations/clickup.mdx
Line: 41| <Step title="Authorize Intercom"> | ||
| Go to [Connections](https://app.nango.dev/dev/connections) -> _Add Test Connection_ -> _Authorize_, then log in to Intercom. Later, you'll let your users do the same directly from your app. Nango doesn't provide a test OAuth app for Intercom yet. You'll need to set up your own by following these [instructions](#🧑%E2%80%8D💻-oauth-app-setup). After that, make sure to add the OAuth client ID, secret, and scopes in the integration settings in Nango. | ||
| </Step> | ||
| <Step title="Call the Intercom API"> |
There was a problem hiding this comment.
[Documentation] This link still points to the obsolete 🧑💻 OAuth app setup section, so it no longer navigates anywhere. Please update it to link to the new setup guide that’s listed in the Integration Guides section.
Additional affected locations:
- docs/api-integrations/box.mdx:18
Context for Agents
[**Documentation**]
This link still points to the obsolete `🧑💻 OAuth app setup` section, so it no longer navigates anywhere. Please update it to link to the new setup guide that’s listed in the Integration Guides section.
**Additional affected locations:**
- docs/api-integrations/box.mdx:18
File: docs/api-integrations/intercom.mdx
Line: 18
Migrates:
accelo ✅
amazon ❌ - api route for the proxy is wrong
apollo
asana
attio
box
calendly
clickup
confluence
discord
dropbox
freshdesk
github-app
github-app-oauth
google-ads
google-analytics
google-docs
instagram
intercom
linear
linkedin
microsoft
microsoft-teams
one-drive
outlook
pipedrive
quickbooks
salesforce-sandbox
sharepoint-online
stripe
twitter-v2
whatsapp-business
xero
youtube
zendesk
zoom
zoho-crm
Docs Migration Second Wave: Standardize Integration Guides in New Hub
This PR advances the documentation migration by moving dozens of connector guides from the legacy
docs/integrations/all/section into the newerdocs/api-integrations/hierarchy. Each guide now follows the refreshed template with updated front matter, consistent setup instructions, and current OAuth walkthroughs to align with the modern documentation framework.Supporting assets and author guidance were also refreshed so the new structure is discoverable and maintainable across the product. Navigation manifests, Connect UI references, and
managed-manifest.jsonwere updated, while.claude/skills/creating-integration-docs/SKILL.mdandAGENTS.mdnow describe the revised workflow and contributor expectations. Broken links and outdated assets were cleaned up, though Amazon integration docs remain partially blocked pending a proxy fix and future redirect work.Key Changes
• Migrated 40+ connector guides from
docs/integrations/all/to the newdocs/api-integrations/hub with standardized templates and updated OAuth content• Updated navigation manifests, Connect UI references, and
managed-manifest.jsonto point to the new documentation paths• Refreshed contributor guidance in
.claude/skills/creating-integration-docs/SKILL.mdandAGENTS.md, and fixed image assets and broken links uncovered during migration• Documented outstanding follow-up for Amazon integration docs and pending redirects from legacy URLs
Affected Areas
• docs/api-integrations/
• docs/integrations/all/
• managed-manifest.json
• Connect UI documentation references
• .claude/skills/creating-integration-docs/SKILL.md
• AGENTS.md
This summary was automatically generated by @propel-code-bot