Reorganize docs with goal-based navigation for LLM-friendly routing #704
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This PR restructures the documentation to help users (especially AI coding agents) quickly identify which path to take when learning Arcade. Key changes: - Add "What do you want to do?" decision tree on homepage - Create goal-based top-level sections: Use Tools, Build Tools, Tool Catalog - Separate Auth Providers from References with clarifying callouts - Add new Help section with Troubleshooting guide - Add clarifying notes distinguishing OAuth config from tool integrations New sections: - /use-tools/ide - For IDE/MCP client users (recommends MCP Gateways) - /use-tools/agent - For app builders (includes auth patterns guide) - /build-tools - For custom tool creators - /auth-providers - Separated OAuth config with clear distinction from tools - /tool-catalog - Renamed integrations entry point - /security - Elevated security content - /help - Consolidated help resources with troubleshooting This addresses confusion between OAuth providers and tool integrations, and provides clear routing for different user goals. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| - **Looking for ready-to-use tools?** → Go to [Tool Catalog](/tool-catalog) | ||
| - **Want to use Gmail, Slack, GitHub tools?** → Go to [Tool Catalog](/tool-catalog) | ||
| - **Need to configure custom OAuth?** → You're in the right place! |
Contributor
There was a problem hiding this comment.
Google.Exclamation: Removed exclamation point as flagged by style guide
Suggested change
| - **Need to configure custom OAuth?** → You're in the right place! | |
| - **Need to configure custom OAuth?** → You're in the right place. |
|
|
||
| ## Adding a Custom OAuth Provider | ||
|
|
||
| If the service you need isn't in our list, you can add a custom OAuth 2.0 provider. |
Contributor
There was a problem hiding this comment.
Google.We: Replaced 'our' to avoid first-person plural
Suggested change
| If the service you need isn't in our list, you can add a custom OAuth 2.0 provider. | |
| If the service you need isn't in the list, you can add a custom OAuth 2.0 provider. |
| Need tools that don't exist in the catalog? Build your own MCP servers with custom logic and authentication. | ||
|
|
||
| <Callout type="info"> | ||
| **Looking for pre-built tools?** Check the [Tool Catalog](/tool-catalog) first - we have 100+ integrations ready to use. |
Contributor
There was a problem hiding this comment.
Google.We: Replace 'we' with 'Arcade' to avoid first-person plural
Suggested change
| **Looking for pre-built tools?** Check the [Tool Catalog](/tool-catalog) first - we have 100+ integrations ready to use. | |
| **Looking for pre-built tools?** Check the [Tool Catalog](/tool-catalog) first - Arcade has 100+ integrations ready to use. |
| - [Self-host with Arcade Engine](/guides/deployment-hosting/configure-engine) | ||
| - [On-premise options](/guides/deployment-hosting/on-prem) | ||
|
|
||
| ## Example: Simple Custom Tool |
Contributor
There was a problem hiding this comment.
alex.Condescending: Remove 'Simple' to avoid condescending language
Suggested change
| ## Example: Simple Custom Tool | |
| ## Example: Custom Tool |
| # Your custom business logic here | ||
| base_rate = 5.00 | ||
| per_kg_rate = 2.50 | ||
| international_surcharge = 10.00 if destination_country != "US" else 0 |
Contributor
There was a problem hiding this comment.
Google.We: Replace 'US' abbreviation with full country name
Suggested change
| international_surcharge = 10.00 if destination_country != "US" else 0 | |
| international_surcharge = 10.00 if destination_country != "United States" else 0 |
|
|
||
| # Quick Start: Your First Custom Tool | ||
|
|
||
| Build a simple custom tool in under 5 minutes. This tutorial will help you understand the basics of creating MCP servers with Arcade. |
Contributor
There was a problem hiding this comment.
alex.Condescending: Removed 'simple' to avoid condescending language
Suggested change
| Build a simple custom tool in under 5 minutes. This tutorial will help you understand the basics of creating MCP servers with Arcade. | |
| Build a custom tool in under 5 minutes. This tutorial will help you understand the basics of creating MCP servers with Arcade. |
|
|
||
| ## What's Next? | ||
|
|
||
| You've built your first custom tool! Here's where to go next: |
Contributor
There was a problem hiding this comment.
Google.Exclamation: Removed exclamation point from text
Suggested change
| You've built your first custom tool! Here's where to go next: | |
| You've built your first custom tool. Here's where to go next: |
| @@ -0,0 +1,16 @@ | |||
| --- | |||
| title: "Contact Us" | |||
Contributor
There was a problem hiding this comment.
Google.We: Remove first-person plural 'Us' from title
Suggested change
| title: "Contact Us" | |
| title: "Contact" |
|
|
||
| import { Callout } from "nextra/components"; | ||
|
|
||
| # Contact Us |
Contributor
There was a problem hiding this comment.
Google.We: Remove first-person plural 'Us' from heading
Suggested change
| # Contact Us | |
| # Contact |
|
|
||
| ## In the Meantime | ||
|
|
||
| See the existing contact page: [Resources Contact](/resources/contact-us) |
Contributor
There was a problem hiding this comment.
Google.We: Remove first-person plural 'us' from URL reference
Suggested change
| See the existing contact page: [Resources Contact](/resources/contact-us) | |
| See the existing contact page: [Resources Contact](/resources/contact) |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR restructures the documentation to help users (especially AI coding agents) quickly identify which path to take when learning Arcade.
Based on feedback from watching customers struggle with using Claude Code to build with Arcade, this reorganization:
New Structure
/use-tools/ide/use-tools/agent/build-tools/auth-providers/tool-catalog/security/helpKey Additions
/use-tools/agent/auth-patterns) - Pre-auth, user-facing, headless patternsScreenshots
The homepage now includes a "What do you want to do?" section right after the hero:
Each path is color-coded and includes a clarifying note about the difference between integrations and auth providers.
Test plan
🤖 Generated with Claude Code