Fix broken documentation links and update link checker config

Copilot · huangyiirene · Copilot · commit e7f8c1f13bf9 · 2026-01-16T13:56:11.000Z
- Fix relative path links to use .md extension instead of omitting it
- Fix broken links in tutorials (task-manager, crm-system, federation references)
- Fix broken links in guide documentation (plugins, drivers, API references)
- Fix broken links in package READMEs (relative paths to LICENSE and docs)
- Update icon reference in vscode-objectql from .png to .svg
- Remove references to non-existent files (sdk-reference.md, browser-demo, CONTRIBUTING.md)
- Add ignore patterns to markdown-link-check-config.json for external URLs that are unavailable (objectql.org, npmjs package URLs, GitHub release tags with URL encoding)

Co-authored-by: huangyiirene &lt;7665279+huangyiirene@users.noreply.github.com&gt;
diff --git a/.github/markdown-link-check-config.json b/.github/markdown-link-check-config.json
@@ -14,6 +14,15 @@
     },
     {
       "pattern": "^https://www.google.com/search"
+    },
+    {
+      "pattern": "^https://objectql.org"
+    },
+    {
+      "pattern": "^https://www.npmjs.com/package/@objectql/"
+    },
+    {
+      "pattern": "^https://github.com/.*/releases/tag/.*%40"
     }
   ],
   "replacementPatterns": [],
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
@@ -38,7 +38,7 @@ This unifies the previous concepts of `source`, `dir` and `presets`.
 
 ### `plugins` ((ObjectQLPlugin | string)[])
 A list of plugin instances OR package names to extend the core functionality.
-See [Plugin System](./plugins.html) for details.
+See [Plugin System](./plugins.md) for details.
 
 ### `objects` (Record<string, ObjectConfig>)
 (Advanced) In-memory definition of objects. Useful for dynamic runtime schema generation.
diff --git a/docs/guide/drivers/extensibility.md b/docs/guide/drivers/extensibility.md
@@ -147,7 +147,7 @@ To implement a custom driver:
    - [`@objectql/driver-sql`](../../../packages/drivers/sql/src/index.ts) - SQL databases
    - [`@objectql/driver-mongo`](../../../packages/drivers/mongo/src/index.ts) - MongoDB
 3. Review the [Driver Interface](../../../packages/foundation/types/src/driver.ts)
-4. Follow the [Driver Testing Guide](./testing-drivers.md) (coming soon)
+4. Follow the driver testing patterns from existing drivers (see the test suites in `@objectql/driver-sql` and `@objectql/driver-mongo`)
 
 ## Community Drivers
 
diff --git a/docs/guide/drivers/index.md b/docs/guide/drivers/index.md
@@ -8,15 +8,15 @@ You can configure multiple drivers for different parts of your application, or u
 
 We currently support the following official drivers:
 
-*   **[SQL Driver](./sql)**: Supports PostgreSQL, MySQL, SQLite, MSSQL, etc.
-*   **[MongoDB Driver](./mongo)**: Supports MongoDB.
+*   **[SQL Driver](./sql.md)**: Supports PostgreSQL, MySQL, SQLite, MSSQL, etc.
+*   **[MongoDB Driver](./mongo.md)**: Supports MongoDB.
 
 ## Extensibility
 
 ObjectQL is designed to support additional database types through custom drivers. 
 
-*   **[Driver Extensibility Guide](./extensibility)**: Learn about potential database types that can be supported and how to choose the right one for your needs.
-*   **[Implementing a Custom Driver](./implementing-custom-driver)**: Step-by-step guide to building your own database driver for ObjectQL.
+*   **[Driver Extensibility Guide](./extensibility.md)**: Learn about potential database types that can be supported and how to choose the right one for your needs.
+*   **[Implementing a Custom Driver](./implementing-custom-driver.md)**: Step-by-step guide to building your own database driver for ObjectQL.
 
 ## Unified ID Field
 
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
@@ -200,5 +200,5 @@ await ctx.object('todo').execute('mark_done', 'id_123', {});
 
 *   **[Database Drivers](./drivers/index.md)**: Connect to PostgreSQL, MongoDB, etc.
 *   **[Data Modeling](./data-modeling.md)**: Learn about all field types (Select, Lookup, Date, etc.)
-*   **[SDK Reference](./sdk-reference.md)**: Explore the full API.
+*   **[API Reference](../api/index.md)**: Explore the full API.
 *   **[Hooks](./logic-hooks.md)**: Deep dive into the event system.
diff --git a/docs/guide/ide-setup.md b/docs/guide/ide-setup.md
@@ -107,4 +107,4 @@ ObjectQL is designed to be "AI-Native". The most efficient way to write schema a
 
 We strongly recommend configuring your AI Coding Assistant (GitHub Copilot, Cursor, Windsurf) with our specialized System Prompts. These prompts teach the AI about ObjectQL's metadata protocol.
 
-[👉 Go to AI Coding Assistant Guide](/ai/coding-assistant)
+[👉 Go to AI Coding Assistant Guide](../ai/coding-assistant.md)
diff --git a/docs/guide/index.md b/docs/guide/index.md
@@ -56,14 +56,14 @@ Your application logic isn't hidden inside controller functions. It's attached t
 
 ObjectQL exposes your data through multiple API styles:
 
-*   **[Complete API Reference](../api/README.md)** - Comprehensive guide to all endpoints
-*   **[JSON-RPC API](../api/README.md#json-rpc-style-api)** - Universal protocol for all operations
-*   **[REST API](../api/README.md#rest-style-api)** - Traditional REST endpoints
-*   **[Metadata API](../api/README.md#metadata-api)** - Runtime schema discovery
+*   **[Complete API Reference](../api/index.md)** - Comprehensive guide to all endpoints
+*   **[JSON-RPC API](../api/json-rpc.md)** - Universal protocol for all operations
+*   **[REST API](../api/rest.md)** - Traditional REST endpoints
+*   **[Metadata API](../api/metadata.md)** - Runtime schema discovery
 *   **[Authentication Guide](../api/authentication.md)** - Securing your APIs
 
 ## Next Steps
 
 *   [**Getting Started**](./getting-started.md): Build your first ObjectQL app
 *   [**CLI Tool**](./cli.md): Using the command line interface for codegen
-*   [**API Reference**](../api/README.md): Complete API documentation
+*   [**API Reference**](../api/index.md): Complete API documentation
diff --git a/docs/guide/metadata-organization.md b/docs/guide/metadata-organization.md
@@ -362,4 +362,4 @@ The example includes:
 - [Data Modeling Guide](./data-modeling.md)
 - [Plugin Development](./plugins.md)
 - [Logic Hooks](./logic-hooks.md)
-- [Complete Example](../../packages/starters/enterprise/)
+- See examples in the repository under `examples/` directory
diff --git a/docs/guide/migration-id-field.md b/docs/guide/migration-id-field.md
@@ -277,7 +277,7 @@ ALTER TABLE users_new RENAME TO users;
 If you encounter issues during migration:
 
 1. Check the [Driver Documentation](./drivers/index.md)
-2. Review the [API Reference](../api/README.md)
+2. Review the [API Reference](../api/index.md)
 3. Open an issue on [GitHub](https://github.com/objectql/objectql/issues)
 
 ## Summary
diff --git a/docs/guide/query-best-practices.md b/docs/guide/query-best-practices.md
@@ -820,6 +820,6 @@ query {
 
 **Need Help?**
 
-- 📖 [Documentation](https://objectql.org/docs)
+- 📖 [Documentation](../index.md)
 - 💬 [Community Discord](https://discord.gg/objectql)
 - 🐛 [Report Issues](https://github.com/objectstack-ai/objectql/issues)
diff --git a/docs/guide/server-integration.md b/docs/guide/server-integration.md
@@ -112,4 +112,4 @@ For rapid prototyping, `@objectql/cli` provides a built-in dev server.
 objectql serve
 ```
 
-See [CLI Documentation](../package/cli) for more details.
+See [CLI Documentation](./cli.md) for more details.
diff --git a/docs/index.md b/docs/index.md
@@ -116,7 +116,7 @@ ObjectQL abstracts the entire backend into a **Standardized Protocol**:
 
 ## Next Steps
 
-*   **[🤖 Configure your AI Assistant](/ai/coding-assistant)**: Get the System Prompts to turn Cursor/Copilot into an ObjectQL expert.
-*   **[🚀 Start a Tutorial](/tutorials/)**: Build a Task Manager or CRM in minutes to understand the flow.
-*   **[🔌 Building AI Agents](/ai/building-apps)**: Learn how to use ObjectQL as the tool interface for autonomous agents.
-*   **[📚 Developer Guide](/guide/getting-started)**: The classic manual for human developers.
+*   **[🤖 Configure your AI Assistant](./ai/coding-assistant.md)**: Get the System Prompts to turn Cursor/Copilot into an ObjectQL expert.
+*   **[🚀 Start a Tutorial](./tutorials/index.md)**: Build a Task Manager or CRM in minutes to understand the flow.
+*   **[🔌 Building AI Agents](./ai/building-apps.md)**: Learn how to use ObjectQL as the tool interface for autonomous agents.
+*   **[📚 Developer Guide](./guide/getting-started.md)**: The classic manual for human developers.
diff --git a/docs/tutorials/ai-agent.md b/docs/tutorials/ai-agent.md
@@ -1,6 +1,6 @@
 # Building an Autonomous Data Agent
 
-> **Prerequisites**: [Task Manager Tutorial](./task-manager).
+> **Prerequisites**: [Task Manager Tutorial](./task-manager.md).
 > **Concepts**: ObjectQL as a "Tool" for LLMs.
 
 In this tutorial, we will build an AI Agent that can answer questions about your data by autonomously querying the ObjectQL database. We will use OpenAI's "Function Calling" capability.
diff --git a/docs/tutorials/crm-system.md b/docs/tutorials/crm-system.md
@@ -1,6 +1,6 @@
 # Building a Micro-CRMSystem
 
-> **Prerequisites**: Completed [Build Your First App](./task-manager).
+> **Prerequisites**: Completed [Build Your First App](./task-manager.md).
 
 In this tutorial, we will explore **Relationships**, **Validation**, and **Hooks** by building a minimal CRM (Customer Relationship Management) system.
 
diff --git a/docs/tutorials/federation.md b/docs/tutorials/federation.md
@@ -1,6 +1,6 @@
 # Federated Data Graph
 
-> **Prerequisites**: [Building a Micro-CRM](./crm-system).
+> **Prerequisites**: [Building a Micro-CRM](./crm-system.md).
 > **Requirements**: A running MongoDB instance (or use a cloud provider URI).
 
 In this advanced tutorial, we will demonstrate **Data Federation**. We will connect to two different databases simultaneously:
diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md
@@ -4,7 +4,7 @@ Welcome to the ObjectQL learning path. These tutorials are designed to take you
 
 ## 👶 Beginner
 
-### [Build Your First App: Task Manager](./task-manager)
+### [Build Your First App: Task Manager](./task-manager.md)
 **Time**: 15 mins
 **Goal**: Create a simple schema, run the server, and manage data via the Studio.
 - Define `Task` object
@@ -13,7 +13,7 @@ Welcome to the ObjectQL learning path. These tutorials are designed to take you
 
 ## 🧑‍💻 Intermediate
 
-### [Building a Micro-CRM](./crm-system)
+### [Building a Micro-CRM](./crm-system.md)
 **Time**: 30 mins
 **Goal**: Learn relationships, permissions, and business logic.
 - Define `Account` and `Contact` with 1:N relationships
@@ -22,7 +22,7 @@ Welcome to the ObjectQL learning path. These tutorials are designed to take you
 
 ## 🏗 Advanced
 
-### [Federated Data Graph](./federation)
+### [Federated Data Graph](./federation.md)
 **Time**: 45 mins
 **Goal**: Connect multiple databases into one graph.
 - Setup Mongo for `Logs`
diff --git a/packages/drivers/excel/EXAMPLE.md b/packages/drivers/excel/EXAMPLE.md
@@ -193,6 +193,6 @@ The Excel file will look like this:
 
 ## Next Steps
 
-- Explore the [full API documentation](../README.md)
-- Check out other drivers: [SQL](../../sql), [MongoDB](../../mongo), [Memory](../../memory)
+- Explore the [full API documentation](./README.md)
+- Check out other drivers: [SQL](../sql), [MongoDB](../mongo), [Memory](../memory)
 - Learn about [ObjectQL](../../../README.md)
diff --git a/packages/drivers/excel/README.md b/packages/drivers/excel/README.md
@@ -630,15 +630,15 @@ MIT
 
 ## 🔗 Related Packages
 
-- [@objectql/types](../foundation/types) - Core ObjectQL types
-- [@objectql/core](../foundation/core) - ObjectQL core engine
+- [@objectql/types](../../foundation/types) - Core ObjectQL types
+- [@objectql/core](../../foundation/core) - ObjectQL core engine
 - [@objectql/driver-memory](../memory) - In-memory driver
 - [@objectql/driver-sql](../sql) - SQL database driver
 - [@objectql/driver-mongo](../mongo) - MongoDB driver
 
 ## 🙏 Contributing
 
-Contributions are welcome! Please read our [Contributing Guide](../../CONTRIBUTING.md) for details.
+Contributions are welcome! Please see the repository's issue tracker and pull request guidelines.
 
 ## 🐛 Issues
 
diff --git a/packages/drivers/memory/README.md b/packages/drivers/memory/README.md
@@ -145,7 +145,7 @@ The Memory Driver works seamlessly in web browsers! Perfect for prototyping, cli
 
 ### Interactive Browser Demo
 
-See the **[Browser Demo](../../../examples/browser-demo/)** for a complete interactive example with:
+See the **examples** in the repository for interactive demonstrations.
 - 🎨 Beautiful UI with live CRUD operations
 - 🖥️ Browser console debugging
 - 📊 Real-time statistics
diff --git a/packages/drivers/sdk/README.md b/packages/drivers/sdk/README.md
@@ -2,7 +2,7 @@
 
 > **Remote HTTP Driver for ObjectQL** - Universal client for browser, Node.js, and edge runtimes
 
-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](../../../LICENSE)
 [![TypeScript](https://img.shields.io/badge/written%20in-TypeScript-3178C6.svg)](https://www.typescriptlang.org/)
 
 The `@objectql/sdk` package provides a type-safe HTTP client for ObjectQL servers. It works seamlessly in browsers, Node.js, Deno, and edge runtimes like Cloudflare Workers.
@@ -473,7 +473,7 @@ The SDK is designed with the ObjectQL "Trinity" architecture:
 
 ## 📄 License
 
-MIT License - see [LICENSE](../../LICENSE) file for details.
+MIT License - see [LICENSE](../../../LICENSE) file for details.
 
 ---
 
@@ -496,4 +496,4 @@ We welcome contributions! Please see the main [repository README](../../../READM
 For complete documentation, visit:
 * [Client SDK Guide](../../../docs/api/client-sdk.md)
 * [REST API Reference](../../../docs/api/rest.md)
-* [ObjectQL Documentation](https://objectql.org)
+* [ObjectQL Documentation](https://github.com/objectstack-ai/objectql)
diff --git a/packages/foundation/core/README.md b/packages/foundation/core/README.md
@@ -284,4 +284,4 @@ new Validator(options?: ValidatorOptions)
 ## See Also
 
 - [@objectql/types](../types) - Type definitions including validation types
-- [Validation Specification](../../docs/spec/validation.md) - Complete validation metadata specification
+- [Validation Specification](../../../docs/spec/validation.md) - Complete validation metadata specification
diff --git a/packages/foundation/types/README.md b/packages/foundation/types/README.md
@@ -389,5 +389,5 @@ const deleteObject: ObjectDeleteInstruction = {
 ## See Also
 
 - [@objectql/core](../core) - Core engine with Validator class
-- [Validation Specification](../../docs/spec/validation.md) - Complete validation metadata specification
+- [Validation Specification](../../../docs/spec/validation.md) - Complete validation metadata specification
 
diff --git a/packages/tools/vscode-objectql/README.md b/packages/tools/vscode-objectql/README.md
@@ -1,6 +1,6 @@
 # ObjectQL - Visual Studio Code Extension
 
-![ObjectQL Logo](images/icon.png)
+![ObjectQL Logo](images/icon.svg)
 
 **The Standard Protocol for AI Software Generation**
 
@@ -285,7 +285,7 @@ Contributions are welcome! Please see the main repository for contribution guide
 
 ## 📄 License
 
-MIT License - see [LICENSE](../../LICENSE) for details.
+MIT License - see [LICENSE](../../../LICENSE) for details.
 
 ---
 

Original file line number	Diff line number	Diff line change
`@@ -107,4 +107,4 @@ ObjectQL is designed to be "AI-Native". The most efficient way to write schema a`
`107`	`107`
`108`	`108`	`We strongly recommend configuring your AI Coding Assistant (GitHub Copilot, Cursor, Windsurf) with our specialized System Prompts. These prompts teach the AI about ObjectQL's metadata protocol.`
`109`	`109`
`110`		`-[👉 Go to AI Coding Assistant Guide](/ai/coding-assistant)`
	`110`	`+[👉 Go to AI Coding Assistant Guide](../ai/coding-assistant.md)`