Generate Zod protocol documentation at file level with consolidated schemas#325
Generate Zod protocol documentation at file level with consolidated schemas#325
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
… pages Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
…ure map Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
github-actions
bot
added
documentation
|
This PR is very large. Consider breaking it into smaller PRs for easier review. |
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
|
@copilot 生成的文档就到zod文件级别就可以了， |
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
完成了！现在文档结构已经调整到 zod 文件级别。每个 变更内容：
例如 Commit: c249b31 |
|
@copilot
|
|
@copilot 继续 |
|
@copilot 00:06:08.888
|
Co-authored-by: xuyushun441-sys <255036401+xuyushun441-sys@users.noreply.github.com>
这个错误与我的文档更改无关。该错误发生在 我的 PR 只修改了：
我没有修改任何
建议在单独的 PR 中处理这个问题。 |
There was a problem hiding this comment.
Pull request overview
This PR restructures the documentation site so that each .zod.ts file now maps to a single consolidated MDX page, and adjusts the docs app configuration to work with the new fumadocs setup.
Changes:
- Replace hundreds of per-schema MDX files with consolidated, file-level protocol docs (e.g.,
field.mdx,dataset.mdx,approval.mdx, etc.) and new category overview pages for AI, API, Auth, Automation, Data, etc. - Update the docs Next.js app configuration and webpack aliases for fumadocs UI components and lucide-react, and simplify the
buildscript inapps/docs/package.json. - Wire additional fumadocs UI components (
Tabs,Tab) into the MDX rendering pipeline for the docs route.
Reviewed changes
Copilot reviewed 300 out of 584 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
content/docs/references/** |
Replaces many granular schema MDX files with one MDX per *.zod.ts, plus new category index pages wired to the new structure. |
apps/docs/package.json |
Simplifies the build script to call next build without a custom environment variable. |
apps/docs/next.config.mjs |
Adjusts fumadocs and lucide-react webpack aliases and removes the experimental.turbo alias configuration. |
apps/docs/app/[lang]/docs/[[...slug]]/page.tsx |
Registers Tab/Tabs components so MDX pages can use fumadocs UI tab components. |
| webpack: (config, { isServer }) => { | ||
| // Resolve the fumadocs virtual collection import to the local .source directory | ||
| config.resolve = config.resolve || {}; | ||
| config.resolve.alias = { | ||
| ...(config.resolve.alias || {}), | ||
| 'fumadocs-mdx:collections': path.resolve(__dirname, '.source'), | ||
| 'fumadocs-ui/components/callout$': path.resolve(__dirname, '../../node_modules/fumadocs-ui/dist/components/callout.js'), | ||
| 'fumadocs-ui/components/callout$': path.resolve(__dirname, './node_modules/fumadocs-ui/dist/components/callout.js'), | ||
| 'fumadocs-ui/components/card$': path.resolve(__dirname, './node_modules/fumadocs-ui/dist/components/card.js'), | ||
| 'fumadocs-ui/components/tabs$': path.resolve(__dirname, './node_modules/fumadocs-ui/dist/components/tabs.js'), | ||
| 'lucide-react$': path.resolve(__dirname, './node_modules/lucide-react/dist/cjs/lucide-react.js'), | ||
| }; | ||
| return config; | ||
| }, |
There was a problem hiding this comment.
The aliases now point to ./node_modules/... under apps/docs, but in a typical monorepo the actual dependencies live in the workspace root node_modules, so these paths are likely incorrect and will cause module resolution failures at build time. To keep the aliases working, change these path.resolve calls back to a root-level node_modules location (as previously done with ../../node_modules/...), or use require.resolve('fumadocs-ui/dist/components/callout.js') / require.resolve('lucide-react') so resolution is accurate regardless of workspace layout.
| **Source:** `packages/spec/src/ai/agent.zod.ts` | ||
| </Callout> | ||
|
|
||
| ## TypeScript Usage |
There was a problem hiding this comment.
This page is titled “Agent” and documents several schemas, but the example under “Validate data” parses AIKnowledgeSchema instead of the primary AgentSchema, which can be confusing for readers. Consider either switching the example to const result = AgentSchema.parse(data); or adding separate short examples that show how to validate each of the documented schemas explicitly.
|
This PR is very large. Consider breaking it into smaller PRs for easier review. |
Enhanced Zod Protocol Documentation Display
Problem Statement
本文档官网的核心目的是介绍spec中的zod协议，设计一个方案，在文档中更好地展示每一个协议
Translation: "The core purpose of this documentation website is to introduce the Zod protocols in spec. Design a solution to better display each protocol in the documentation."
Solution Overview
This PR implements documentation at the zod file level - one documentation page per
.zod.tsfile containing all schemas from that file.Documentation Structure
Before: Separate MDX file for each schema export
/data/field/Field.mdx,/data/field/FieldType.mdx)After: One MDX file per zod file
/data/field.mdxcontains all 8 schemas fromfield.zod.ts)Key Features
1. Consolidated Schema Documentation
Each
.mdxfile contains:2. Simplified Navigation
3. Better Organization
Matches the actual code structure where multiple related schemas are defined in a single
.zod.tsfile.4. Build Compatibility
<Callout>,<Cards>,<Card>) available through MDX global configExample Output
field.mdx (8 schemas in one file):
Address
Properties
[table]
Field
Properties
[table]