Fix: Correct fumadocs link behavior - remove /docs/ prefix from markdown

Copilot · hotlong · Copilot · commit bb5fe3fa75d8 · 2026-01-22T18:16:58.000Z
I misunderstood how fumadocs links work. The baseUrl: '/docs' config means fumadocs AUTOMATICALLY prepends /docs to internal links at runtime. Links in markdown should NOT include /docs/ prefix: - ❌ WRONG: [Guide](/docs/guide/quick-start) → renders as /docs/docs/guide/quick-start - ✅ CORRECT: [Guide](/guide/quick-start) → fumadocs renders as /docs/guide/quick-start Changes: - Reverted all link "fixes" from commit fa7ae26 (those were breaking links) - Updated validation script to detect /docs/ prefix as an ERROR - Updated CONTRIBUTING.md with correct link conventions - Updated scripts/README.md with correct examples - Updated GitHub Actions workflow message with correct guidance This fixes the broken links reported on the Vercel deployment. Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
diff --git a/.github/workflows/validate-docs-links.yml b/.github/workflows/validate-docs-links.yml
@@ -61,8 +61,8 @@ jobs:
             const message = `⚠️ **Documentation Links Validation Found Issues**\n\n` +
               `The validation tool found broken links in the documentation. Run \`pnpm validate:links\` locally to see details.\n\n` +
               `Common issues:\n` +
-              `- Missing \`/docs/\` prefix (internal links should use \`/docs/...\`)\n` +
-              `- Incorrect paths (e.g., \`/api/core\` should be \`/docs/reference/api/core\`, \`/spec/\` should be \`/docs/architecture/\`)\n` +
+              `- Incorrectly including \`/docs/\` prefix (fumadocs adds this automatically, so links should NOT include it)\n` +
+              `- Incorrect paths (e.g., \`/api/core\` should be \`/reference/api/core\`, \`/spec/\` should be \`/architecture/\`)\n` +
               `- Links to non-existent files or routes\n\n` +
               `ℹ️ This is informational only and does not fail the build. Fix these issues in a follow-up PR if needed.`;
             github.rest.issues.createComment({
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -426,30 +426,30 @@ pnpm site:build
 #### ✅ Correct Link Patterns
 
 ```markdown
-<!-- Correct - internal documentation links MUST include /docs/ prefix -->
-[Quick Start](/docs/guide/quick-start)
-[Components](/docs/components)
-[API Reference](/docs/reference/api/core)
-[Protocol Specs](/docs/reference/protocol/overview)
-[Architecture](/docs/architecture/component)
+<!-- Correct - internal links should NOT include /docs/ prefix -->
+[Quick Start](/guide/quick-start)
+[Components](/components)
+[API Reference](/reference/api/core)
+[Protocol Specs](/reference/protocol/overview)
+[Architecture](/architecture/component)
 ```
 
 #### ❌ Incorrect Link Patterns
 
 ```markdown
-<!-- Wrong - missing /docs/ prefix -->
-[Quick Start](/guide/quick-start)       <!-- ❌ Should be /docs/guide/quick-start -->
-[Components](/components)               <!-- ❌ Should be /docs/components -->
+<!-- Wrong - includes /docs/ prefix (fumadocs adds this automatically) -->
+[Quick Start](/docs/guide/quick-start)  <!-- ❌ Should be /guide/quick-start -->
+[Components](/docs/components)          <!-- ❌ Should be /components -->
 
 <!-- Wrong - incorrect paths -->
-[API Reference](/api/core)              <!-- ❌ Should be /docs/reference/api/core -->
-[Spec](/spec/component)                 <!-- ❌ Should be /docs/architecture/component -->
-[Protocol](/protocol/form)              <!-- ❌ Should be /docs/reference/protocol/form -->
+[API Reference](/api/core)              <!-- ❌ Should be /reference/api/core -->
+[Spec](/spec/component)                 <!-- ❌ Should be /architecture/component -->
+[Protocol](/protocol/form)              <!-- ❌ Should be /reference/protocol/form -->
 ```
 
 #### Why?
 
-Fumadocs is configured with `baseUrl: '/docs'`, which means all documentation pages are served under the `/docs` route. Internal links must include the `/docs/` prefix to match the actual URL structure where the pages are accessible.
+Fumadocs is configured with `baseUrl: '/docs'`, which automatically prepends `/docs` to all internal links at runtime. If you include `/docs/` in your markdown links, the final URL will be `/docs/docs/...` (double prefix), causing 404 errors.
 
 #### Validating Links
 
@@ -462,7 +462,7 @@ pnpm validate:links
 
 This will check:
 - Links point to existing files and routes
-- Links use correct path structure
+- Links do NOT incorrectly include /docs/ prefix
 - Suggestions for fixing common issues
 
 The validation runs automatically on PRs that modify documentation files.
diff --git a/docs/README.md b/docs/README.md
@@ -213,7 +213,7 @@ Use relative links for internal documentation:
 
 ```markdown
 See [Schema Rendering](./schema-rendering.md) for details.
-See [Protocol Overview](/docs/reference/protocol/overview) for specs.
+See [Protocol Overview](/protocol/overview) for specs.
 ```
 
 ### Front Matter
diff --git a/docs/architecture/base-components.md b/docs/architecture/base-components.md
@@ -14,7 +14,7 @@ This specification defines the metadata structure for ObjectQL's built-in platfo
 - Enable marketplace distribution
 
 **Scope:** This document covers the complete metadata specification for all platform base components, including data display, data entry, layout, navigation, and visualization components.
-For the low-level UI component library (Button, Input, Dialog, etc.), please refer to the [Component Library Reference](/docs/architecture/component-library).
+For the low-level UI component library (Button, Input, Dialog, etc.), please refer to the [Component Library Reference](component-library.md).
 
 ## 2. Base Component Categories
 
diff --git a/docs/concepts/component-registry.md b/docs/concepts/component-registry.md
@@ -459,10 +459,10 @@ export { RatingComponent }
 
 - [Expression System](./expressions.md) - Learn about dynamic expressions
 - [Schema Rendering](./schema-rendering.md) - Understand the rendering engine
-- [Creating Custom Components](/docs/architecture/component-package) - Deep dive into component creation
+- [Creating Custom Components](/spec/component-package.md) - Deep dive into component creation
 
 ## Related Documentation
 
-- [Core API](/docs/reference/api/core) - Component registry API
-- [React API](/docs/reference/api/react) - React integration
-- [Component Specification](/docs/architecture/component) - Component metadata spec
+- [Core API](/api/core) - Component registry API
+- [React API](/api/react) - React integration
+- [Component Specification](/spec/component.md) - Component metadata spec
diff --git a/docs/concepts/expressions.md b/docs/concepts/expressions.md
@@ -636,10 +636,10 @@ const data: UserData = { /* ... */ }
 
 - [Schema Rendering](./schema-rendering.md) - Learn the rendering engine
 - [Component Registry](./component-registry.md) - Understand components
-- [Protocol Overview](/docs/reference/protocol/overview) - Explore schema specifications
+- [Protocol Overview](/protocol/overview) - Explore schema specifications
 
 ## Related Documentation
 
-- [Core API](/docs/reference/api/core) - Expression evaluator API
-- [Form Protocol](/docs/reference/protocol/form) - Form-specific expressions
-- [View Protocol](/docs/reference/protocol/view) - Data view expressions
+- [Core API](/api/core) - Expression evaluator API
+- [Form Protocol](/protocol/form) - Form-specific expressions
+- [View Protocol](/protocol/view) - Data view expressions
diff --git a/docs/concepts/plugins.md b/docs/concepts/plugins.md
@@ -373,7 +373,7 @@ export function registerComponents() {
 - [Component Registry](./component-registry.md) - Understanding the registry
 - [Schema Rendering](./schema-rendering.md) - How schemas become UI
 - [Lazy-Loaded Plugins Architecture](./lazy-loading.md) - Deep dive
-- [Creating Components](/docs/architecture/component-package) - Component development
+- [Creating Components](/spec/component-package.md) - Component development
 
 ## Next Steps
 
diff --git a/docs/concepts/schema-rendering.md b/docs/concepts/schema-rendering.md
@@ -411,11 +411,11 @@ Always type your schemas for better IDE support and fewer runtime errors.
 
 - [Component Registry](./component-registry.md) - Learn about component registration
 - [Expression System](./expressions.md) - Master expressions
-- [Protocol Overview](/docs/reference/protocol/overview) - Explore all available schemas
+- [Protocol Overview](/protocol/overview) - Explore all available schemas
 
 ## Related Documentation
 
-- [Rendering Specification](/docs/architecture/rendering-specification) - Technical specification
-- [Architecture](/docs/architecture) - System architecture
-- [Core API](/docs/reference/api/core) - Core package API reference
-- [React API](/docs/reference/api/react) - React package API reference
+- [Schema Specification](/spec/schema-rendering) - Technical specification
+- [Architecture](/spec/architecture) - System architecture
+- [Core API](/api/core) - Core package API reference
+- [React API](/api/react) - React package API reference
diff --git a/docs/guide/studio.md b/docs/guide/studio.md
@@ -189,10 +189,10 @@ It is **not** designed for:
 
 ## What's Next?
 
-- [Read the full guide](/docs/guide)
-- [Explore the API reference](/docs/reference/api/react)
-- [Check out component specifications](/docs/reference/protocol/overview)
-- [View the project roadmap](https://github.com/objectstack-ai/objectui)
+- [Read the full guide](/docs/guide/introduction)
+- [Explore the API reference](/docs/api/react)
+- [Check out component specifications](/docs/protocol/overview)
+- [View the project roadmap](/ROADMAP)
 
 ## Feedback
 
diff --git a/docs/migration/from-objectstack.md b/docs/migration/from-objectstack.md
@@ -148,7 +148,7 @@ The integration follows this hierarchy:
 
 If you encounter any issues:
 
-1. Check the [adapter README](https://github.com/objectstack-ai/objectui/tree/main/packages/core/src/adapters)
+1. Check the [adapter README](packages/core/src/adapters/README.md)
 2. Review the [ObjectStack spec](https://github.com/objectstack-ai/spec)
 3. Open an issue on GitHub
 
diff --git a/docs/plugins/plugin-markdown.mdx b/docs/plugins/plugin-markdown.mdx
@@ -189,7 +189,7 @@ npm install our-package
 2. Configure your settings
 3. Start building!
 
-For more information, see the [API Reference](/docs/reference/api).
+For more information, see the [API Reference](/api).
   `,
   className: 'prose prose-lg max-w-none'
 }
@@ -230,7 +230,7 @@ app.run()
 
 ## Contributing
 
-Contributions are welcome! Please read our [contributing guidelines](https://github.com/objectstack-ai/objectui/blob/main/CONTRIBUTING.md).
+Contributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md).
 
 ## License
 
diff --git a/docs/plugins/plugin-object.mdx b/docs/plugins/plugin-object.mdx
@@ -539,7 +539,7 @@ const dataSource = new ObjectQLDataSource({
 
 ## Related Documentation
 
-- [ObjectQL Integration](/docs/ecosystem/objectql)
-- [Data Sources](/docs/concepts/data-source)
+- [ObjectQL Integration](/docs/ecosystem/objectql.md)
+- [Data Sources](/docs/concepts/data-source.md)
 - [Plugin System Overview](/docs/concepts/plugins)
 - [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-object)
diff --git a/docs/reference/protocol/crud.md b/docs/reference/protocol/crud.md
@@ -497,5 +497,5 @@ See [examples/user-management](../../examples/user-management) for a complete wo
 
 - [Action Schema](./action.md)
 - [Detail Schema](./detail.md)
-- [API Integration](/docs/ecosystem/api)
+- [API Integration](/ecosystem/api.md)
 - [Event Handling](./events.md)
diff --git a/docs/reference/protocol/overview.md b/docs/reference/protocol/overview.md
@@ -10,13 +10,13 @@ The protocol is organized into several core types, each representing a different
 
 ### Core Types
 
-- **[Object](/docs/reference/protocol/object)** 📝 Planned - Data models and CRUD operations
-- **[View](/docs/reference/protocol/view)** ✅ Implemented - Data visualization (list, table, kanban, etc.)
-- **[Page](/docs/reference/protocol/page)** 🚧 Partial - Page layouts and structure
-- **[Form](/docs/reference/protocol/form)** ✅ Implemented - Form definitions and validation
-- **[Menu](/docs/reference/protocol/menu)** 🚧 Partial - Navigation menus and breadcrumbs
-- **[App](/docs/reference/protocol/app)** 📝 Planned - Application configuration
-- **[Report](/docs/reference/protocol/report)** 📝 Planned - Reports and analytics
+- **[Object](/protocol/object)** 📝 Planned - Data models and CRUD operations
+- **[View](/protocol/view)** ✅ Implemented - Data visualization (list, table, kanban, etc.)
+- **[Page](/protocol/page)** 🚧 Partial - Page layouts and structure
+- **[Form](/protocol/form)** ✅ Implemented - Form definitions and validation
+- **[Menu](/protocol/menu)** 🚧 Partial - Navigation menus and breadcrumbs
+- **[App](/protocol/app)** 📝 Planned - Application configuration
+- **[Report](/protocol/report)** 📝 Planned - Reports and analytics
 
 ## Design Principles
 
@@ -256,9 +256,9 @@ Help us improve the protocol:
 
 ## Next Steps
 
-- [Object Protocol](/docs/reference/protocol/object) - Learn about data models
-- [View Protocol](/docs/reference/protocol/view) - Understand data visualization
-- [Page Protocol](/docs/reference/protocol/page) - Master page layouts
+- [Object Protocol](/protocol/object) - Learn about data models
+- [View Protocol](/protocol/view) - Understand data visualization
+- [Page Protocol](/protocol/page) - Master page layouts
 
 ---
 
diff --git a/docs/reference/protocol/page.md b/docs/reference/protocol/page.md
@@ -486,7 +486,7 @@ The ObjectQL Studio provides a visual interface for:
 - [Application Configuration](./application.md)
 - [Form Specification](./form.md)
 - [View Specification](./view.md)
-- [Component Library](/docs/components)
+- [Component Library](/guide/components.md)
 
 ### 1.5 JSON Logic & Expressions
 
@@ -496,4 +496,4 @@ The schema supports expression evaluation for dynamic behavior, using a syntax s
 - **Ternary**: `${isAdmin ? 'Show' : 'Hide'}`
 - **Filters**: `${value | date: 'YYYY-MM-DD'}`
 
-See [Schema Rendering Specification](/docs/concepts/schema-rendering) for deeper details on the rendering engine.
+See [Schema Rendering Specification](/community/architecture/specs/schema-rendering.md) for deeper details on the rendering engine.
diff --git a/docs/versioning.md b/docs/versioning.md
@@ -67,7 +67,7 @@ All packages in the ObjectUI monorepo are versioned together:
 
 ## Changelog
 
-All changes are documented in [CHANGELOG.md](https://github.com/objectstack-ai/objectui/blob/main/CHANGELOG.md) following [Keep a Changelog](https://keepachangelog.com/) format.
+All changes are documented in [CHANGELOG.md](/CHANGELOG.md) following [Keep a Changelog](https://keepachangelog.com/) format.
 
 ### Changelog Categories
 
@@ -226,7 +226,7 @@ Features marked as "experimental" may change without notice:
 
 ### Where to Find Release Notes
 
-- [CHANGELOG.md](https://github.com/objectstack-ai/objectui/blob/main/CHANGELOG.md) - Detailed changes
+- [CHANGELOG.md](/CHANGELOG.md) - Detailed changes
 - [GitHub Releases](https://github.com/objectstack-ai/objectui/releases) - Release highlights
 - [Blog](https://blog.objectui.org) - Feature announcements
 - [Twitter](https://twitter.com/objectui) - Quick updates
diff --git a/scripts/README.md b/scripts/README.md
@@ -19,7 +19,7 @@ node scripts/validate-docs-links.mjs
 
 **What it checks**:
 - ✅ Links point to existing files and routes
-- ✅ Links use correct path structure with `/docs/` prefix
+- ✅ Links do NOT incorrectly include `/docs/` prefix
 - ✅ Provides suggestions for fixing common issues
 
 **Exit codes**:
@@ -35,24 +35,24 @@ When adding internal links in documentation, follow these patterns:
 ### ✅ Correct
 
 ```markdown
-[Quick Start](/docs/guide/quick-start)
-[Components](/docs/components)
-[API Reference](/docs/reference/api/core)
-[Protocol](/docs/reference/protocol/overview)
-[Architecture](/docs/architecture/component)
+[Quick Start](/guide/quick-start)
+[Components](/components)
+[API Reference](/reference/api/core)
+[Protocol](/reference/protocol/overview)
+[Architecture](/architecture/component)
 ```
 
 ### ❌ Incorrect
 
 ```markdown
-[Quick Start](/guide/quick-start)       <!-- ❌ Missing /docs/ prefix -->
-[API](/api/core)                        <!-- ❌ Should be /docs/reference/api/core -->
-[Spec](/spec/component)                 <!-- ❌ Should be /docs/architecture/component -->
+[Quick Start](/docs/guide/quick-start)  <!-- ❌ Don't include /docs/ prefix -->
+[API](/api/core)                        <!-- ❌ Should be /reference/api/core -->
+[Spec](/spec/component)                 <!-- ❌ Should be /architecture/component -->
 ```
 
 ## Why These Conventions?
 
-Fumadocs is configured with `baseUrl: '/docs'`, which means all documentation pages are served under the `/docs` route. Internal links must include the `/docs/` prefix to match the actual URL structure where the pages are accessible.
+Fumadocs is configured with `baseUrl: '/docs'`, which automatically prepends `/docs` to all internal links at runtime. If you include `/docs/` in your markdown links, the final URL will be `/docs/docs/...` (double prefix), causing 404 errors.
 
 ## See Also
 
diff --git a/scripts/validate-docs-links.mjs b/scripts/validate-docs-links.mjs
@@ -107,31 +107,32 @@ function validateLink(link) {
   // Extract the path (remove anchors and query strings)
   let linkPath = url.split('#')[0].split('?')[0];
   
-  // Normalize path - fumadocs internal links should start with /docs/
+  // Normalize path
   if (!linkPath.startsWith('/')) {
     linkPath = '/' + linkPath;
   }
   
-  // For fumadocs, internal documentation links should include /docs/ prefix
-  // since baseUrl: '/docs' defines the route prefix, not a substitution
-  let routePath = linkPath;
+  // IMPORTANT: In fumadocs, internal links should NOT include the baseUrl prefix
+  // The baseUrl ('/docs') is automatically prepended by fumadocs at runtime
+  // So links should be like: /guide/quick-start (not /docs/guide/quick-start)
+  
+  // Check if link incorrectly includes /docs/ prefix
   if (linkPath.startsWith('/docs/')) {
-    // Remove /docs/ prefix to check against available routes
-    routePath = linkPath.substring(5) || '/';
-  } else if (linkPath !== '/' && !linkPath.startsWith('/docs')) {
-    // Links that don't start with /docs/ might be missing the prefix
-    WARNINGS.push({
+    ERRORS.push({
       file: filePath,
       line,
       link: url,
-      message: `Link might be missing /docs/ prefix. Internal links should use /docs/... to match the route structure.`
+      text,
+      error: 'Link incorrectly includes /docs/ prefix. Fumadocs automatically adds the baseUrl, so links should not include it.',
+      suggestion: url.replace('/docs/', '/')
     });
+    return;
   }
   
   // Remove trailing slash for comparison
-  const normalizedPath = routePath.replace(/\/$/, '') || '/';
+  const normalizedPath = linkPath.replace(/\/$/, '') || '/';
   
-  // Check if route exists (after removing /docs/ prefix)
+  // Check if route exists
   if (!VALID_ROUTES.has(normalizedPath) && normalizedPath !== '' && normalizedPath !== '/') {
     ERRORS.push({
       file: filePath,
@@ -160,20 +161,20 @@ function findSimilarRoute(route) {
       const validLastPart = validParts[validParts.length - 1];
       
       if (lastPart === validLastPart) {
-        return `Did you mean: /docs${validRoute}?`;
+        return `Did you mean: ${validRoute}?`;
       }
     }
   }
   
   // Check for common patterns
   if (route.startsWith('/api/')) {
-    return 'API docs are under /docs/reference/api/';
+    return 'API docs are under /reference/api/';
   }
   if (route.startsWith('/spec/')) {
-    return 'Spec docs are under /docs/architecture/';
+    return 'Spec docs are under /architecture/';
   }
   if (route.startsWith('/protocol/')) {
-    return 'Protocol docs are under /docs/reference/protocol/';
+    return 'Protocol docs are under /reference/protocol/';
   }
   
   return null;
