New Information Architecture #622
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
- Migrated 176 files with 2,657 link updates total - Updated links from /home/ paths to new structure: - /get-started/ for onboarding content - /guides/ for how-to guides - /references/ for reference documentation - /resources/ for supplementary content - Based on URL mappings from docs-migration.csv 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
nearestnabors
force-pushed
the
new-ia-backup
branch
from
db404a0 to
f3c7c3a
Compare
- Added 61 permanent (308) redirects in next.config.ts - Maps old /home/ paths to new information architecture - Uses Next.js redirects() for server-side handling - SEO-friendly: search engines will update their indexes 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
- Updated 119 files with remaining /home/ references - Fixed links with anchors and query parameters - Ensured all internal links point to new IA structure - Comprehensive mapping of all /home/ paths to new locations 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
nearestnabors
force-pushed
the
new-ia-backup
branch
from
45b3e52 to
67c1e41
Compare
nearestnabors
force-pushed
the
new-ia-backup
branch
from
84c199a to
67c1e41
Compare
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
app/en/guides/create-tools/tool-basics/compare-server-types/page.mdx
Outdated
Show resolved
Hide resolved
app/en/guides/user-facing-agents/secure-auth-production/page.mdx
Outdated
Show resolved
Hide resolved
nearestnabors
requested review from
evantahler,
sdserranog,
torresmateo and
vfanelle
|
For some reason the integrations aren't being listed alphabetically within their respective category. Additional thoughts (feel free to ignore):
|
evantahler
left a comment
evantahler
left a comment
There was a problem hiding this comment.
I did a review based on the preview site holistically - I haven't reviewed the code. If you would like a code review, @ me on a page and I can take a look!
In general, I like the new IA - I like both the high level categories, and how the user works down form intro to advanced topics as they go.
Some blocking items:
- The sidebar links in the "references" section do not work (either 404 or 'too many redirects'), except for 'auth providers'
- Navigationally, the list of integrations/toolkits moving under 'resources' is fine, but this page is really important for the "should I use Arcade" decision making process. I think that means is should have a top-nav link as well. It should also be called out in some way to differentiate the importance of that page.
- I agree with @EricGustin that the tool-type categorization (productivity, sales, etc) probably matters less than the list of APIs we we support. A categorization I do think matters now is "starter" vs "optimized". We should focus on the starter tools and de-emphasize the starter tools - they are mixed now.
- 'Submit your Server' doesn't do anything
Questions I have:
- The new 'about arcade' is good! How does that relate to the 'home' page - can they be merged or are they doing different jobs?
|
One more nit - the |
|
@EricGustin re:
Yes yes!! We have had user feedback to this end that suggests turning this into just a list, no categories, is what people want. However, I didn't want to make TOO MANY changes in this PR, so that will be a separate one For Discussion. You into it? |
I also feel uneasy about this. But here's what we noticed in user testing—no one was using the Global Nav Bar. They would go to arcade.dev and click the Integrations link from there. When we added the link to the sidebar, they started clicking from there. So this version removes the global navigation bar entirely. Would you feel better if we added it back and had duplication?
Is this a filter we can add to the main page? Because that seems to be the way people prefer to navigate the tools—by filters.
The home page will need to be retooled, IMO ideally to shunt people to different resources, like react.dev and docs.agentql.com do. (Generally, docs landing pages are not the place to sell to new users, but a place to triage incoming users new and old to the right place to get their answers!) I agree we need to update it. But it's for a different PR (and possible workshopping!) |
next.config.ts
Outdated
| { | ||
| source: | ||
| "/en/home/mastra/use-arcade-tools, /en/home/mastra/user-auth-interrupts", | ||
| destination: "/en/guides/agent-frameworks/mastra/typescript", |
There was a problem hiding this comment.
Mastra redirect points to non-existent typescript page
The redirect destination /en/guides/agent-frameworks/mastra/typescript doesn't exist. The mastra folder only contains overview, use-arcade-tools, and user-auth-interrupts according to its _meta.tsx. This will cause a 404 error for users following old mastra documentation links.
Scoping this outside of the current PR makes sense to me. But let's get that conversation rolling! |
Fixed multiple categories of broken links across the documentation: Routing & Redirects: - Removed infinite redirect loops (e.g., /en/references redirecting to itself) - Added proper redirects for MCP paths (/en/references/mcp, /en/references/mcp/python) - Added redirects for paths missing locale prefixes (/mcp-servers/* → /en/resources/integrations/*) - Fixed paths to moved pages (e.g., api-key → api-keys, openai → openai-agents) Link Corrections: - Fixed malformed anchor links missing '#' separator (e.g., googleusing-google-auth → google#using-google-auth) - Updated paths to point to correct locations (e.g., /guides/create-tools/contribute/registry-early-access) - Fixed references in glossary to use correct anchor format Test Updates: - Enhanced broken-link-check.test.ts with comprehensive redirect whitelist - Added handling for both /mcp-servers/* and /en/mcp-servers/* patterns - Updated test to validate redirects match actual file structure All 75 broken links now resolved. Both broken-link-check and internal-link-check tests pass. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
|
I don't want "perfect to be the enemy of done", so now that the links all work, I'd be comfortable merging this as-is, and moving some of the open questions to quick-follow work:
|
|
They're already in docs triage with follow up milestones @evantahler :) However, I did have to push some fixes to broken links and redirects. Please hold |
## Summary Made the documentation system properly multilingual by removing hardcoded English locale prefixes from all internal links and redirect configurations. Nextra automatically handles locale routing, so explicit /en/ prefixes were causing issues and breaking multilingual support. ## Changes Made ### Redirect Configuration (next.config.ts) - Removed /en/ prefixes from all redirect destinations - Fixed infinite redirect loops where paths were redirecting to themselves - Cleaned up duplicate entries from merge conflicts - All redirects now use language-agnostic paths that work with any locale - Verified all redirects from docs-migration.csv are present and correct ### Internal Links - Updated all markdown files to remove hardcoded /en/ prefixes from internal links - Fixed malformed anchor links that were missing '#' separators - Corrected links pointing to wrong auth provider documentation ### Test Updates (tests/broken-link-check.test.ts) - Updated link validation to handle language-agnostic paths - Added redirect mappings for all known redirects - Tests now properly validate links without locale prefixes ## Files Modified - next.config.ts - Removed locale prefixes from all redirects - app/en/references/changelog/page.mdx - Fixed malformed Google auth link - app/en/resources/glossary/page.mdx - Fixed malformed Google auth links - app/en/resources/tools/page.mdx - Removed /en/ from internal links - app/en/resources/integrations/productivity/*.mdx - Fixed Google auth reference links - tests/broken-link-check.test.ts - Updated to handle language-agnostic validation ## Testing ✅ All tests passing (0 broken links) ✅ Verified redirects work correctly without locale prefixes ✅ Confirmed Nextra handles locale routing automatically ✅ Cross-referenced all redirects with docs-migration.csv 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
Updated all internal links to use the correct destination paths instead of redirect paths: - /get-started/setup/api-key → /get-started/setup/api-keys - /references/auth-providers/ → /references/auth-providers (removed trailing slash) - /guides/tool-calling/ → /guides/tool-calling (removed trailing slash) - /references/mcp/python/ → /references/mcp/python - /guides/tool-calling/custom-apps/authorized-tool-calling → /guides/tool-calling/custom-apps/auth-tool-calling - /guides/user-facing-agents/brand-provider → /guides/user-facing-agents/secure-auth-production - /guides/tool-calling/mcp-client/* → /guides/tool-calling/mcp-clients/* - /guides/tool-calling/get-tool-definitions → /guides/tool-calling/custom-apps/get-tool-definitions - /guides/deployment-hosting/engine-configuration → /guides/deployment-hosting/configure-engine - /guides/create-tools/performance/run-evaluations → /guides/create-tools/evaluate-tools/run-evaluations - /references/arcade-cliarcade-configure → /references/arcade-cli - /resources/creating-tools/tool-basics/build-mcp-server → /guides/create-tools/tool-basics/build-mcp-server - /resources/mastra/user-auth-interrupts → /guides/agent-frameworks/mastra/user-auth-interrupts Removed the knownRedirects mapping from the test file since all links now point directly to the correct paths. All tests pass successfully. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
torresmateo
left a comment
torresmateo
left a comment
There was a problem hiding this comment.
I like the new navigation a lot. However (not blocking for this PR):
Behavior
- When I expand a section I expect the remaining state of the sidebar do be unchanged, and I experience some inconsistency here while navigating. To reproduce click "Agent Frameworks" then "LangGraph" then "Quickstarts". When "Quickstarts" is clicked, "Agent Frameworks" is automatically collapsed, which confuses me as too many things happened and I expected only "Quickstarts" to expand.
- When I click an inner link that takes me to another page, I expect the sidebar status to expand the sections to show me the active section I'm currently on, without collapsing everything I manually expanded up to that point. This is likely related to the previous point.
Design
- When I expand things at the third level of nesting, the sidebar is too narrow for the content, and the amount of unused space at the left of the sidebar looks like free real state we could be using. I suggest we stick the sidebar all the way to the left, give it some room to grow horizontally, while keeping the main content centered in it's column. This is probably applicable only to 1440p+ screens only though, this does not bother me while looking at the docs in the laptop screen only
|
@torresmateo I've noted these issues and others in Linear. Let's triage at tomorrow's docs standup |
Preview
Note
Major documentation IA overhaul with new top-level sections and navigation.
get-started,guides,references,resources) with many new/relocated pages and_meta.tsxfiles; removes legacyhomestructure/home/...→/guides/...,/references/...,/resources/integrations/...)app/en/_meta.tsx(iconized titles, breadcrumb/layout settings)BadgeinLogo, adjusteditPagecopy in_dictionaries/en.ts, convert several TSinterfacetypes totype.github/scripts/update-example-dates.jsnow usesnode:imports and points toapp/en/resources/examples/page.mdxtranslate-docs.yml(examplesingle_filepath)*.bakto.gitignoreWritten by Cursor Bugbot for commit f41d1bf. This will update automatically on new commits. Configure here.