catalog-documentation-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

EventCatalog Documentation Creator

EventCatalog 文档创建指南

Generate properly formatted EventCatalog documentation files following project conventions and best practices.

按照项目规范与最佳实践，生成格式规范的EventCatalog文档文件。

Instructions

操作说明

Step 1: Locate or Create the User's Catalog

步骤1：定位或创建用户的目录

Before generating any files, ask the user: "Do you already have an EventCatalog project, or would you like to create a new one?"

If they already have a catalog:

Ask: "Where is your EventCatalog project?" — It could be:
- A repo they've cloned locally (e.g.,
```
~/projects/my-catalog/
```
  )
- A folder on their machine
- A monorepo with the catalog in a subdirectory
Verify it looks like an EventCatalog project by checking for an
```
eventcatalog.config.js
```
file or known directories (
```
services/
```
,
```
events/
```
,
```
domains/
```
, etc.)
Read the existing structure to understand whether they use nested (domains/services/events) or flat (top-level services/, events/) organization

If they don't have a catalog yet:

Ask where they'd like to create it (default: current directory)
Run the following command to scaffold a new empty catalog:
bash
```
npx @eventcatalog/create-eventcatalog@latest my-catalog --empty
```
(Replace
```
my-catalog
```
with the user's preferred name)
This creates a ready-to-use EventCatalog project with the correct structure
All generated documentation files go inside this new catalog directory

CRITICAL: All generated files must be written to the user's catalog directory, not just displayed. Always ask where they want resources documented — never assume.

在生成任何文件之前，请先询问用户：「您已经有EventCatalog项目了吗，还是需要创建一个新项目？」

如果用户已有目录：

询问：「您的EventCatalog项目位于哪里？」 —— 可能的位置包括：
- 本地克隆的仓库（例如：
```
~/projects/my-catalog/
```
  ）
- 本地机器上的某个文件夹
- 单体仓库中某个子目录下的目录
通过检查是否存在
```
eventcatalog.config.js
```
文件或已知目录（
```
services/
```
、
```
events/
```
、
```
domains/
```
等），确认这是一个EventCatalog项目
读取现有结构，了解用户采用的是嵌套式（领域/服务/事件）还是扁平化（顶层services/、events/）组织方式

如果用户还没有目录：

询问用户希望在何处创建目录（默认：当前目录）
运行以下命令搭建一个新的空目录：
bash
```
npx @eventcatalog/create-eventcatalog@latest my-catalog --empty
```
（将
```
my-catalog
```
替换为用户偏好的名称）
该命令会创建一个结构正确、可直接使用的EventCatalog项目
所有生成的文档文件都将放入这个新的目录中

重要提示：所有生成的文件必须写入用户的目录中，不能仅展示。始终询问用户希望将资源记录在何处——切勿自行假设。

Step 2: Understand What the User Wants to Document

步骤2：明确用户的文档记录需求

Ask the user what they want to document. Common scenarios:

A single service and its messages
An event, command, or query
A full domain with nested services
A business flow across services
A channel (Kafka topic, RabbitMQ queue, etc.)
A container (database, cache, queue)

Gather this information before generating:

Resource name and purpose
Version (default to
```
0.0.1
```
for new resources)
Message relationships (what it sends/receives)
Channel routing (what channels messages flow through)
Containers (what databases/caches the service reads from or writes to)
Schema format if applicable (JSON Schema, Avro, Protobuf)

If the user points you at a codebase (not the catalog), analyze it to extract services, messages, schemas, and relationships — then generate the corresponding catalog documentation.

询问用户希望记录的内容，常见场景包括：

单个服务及其消息
某个事件、命令或查询
包含嵌套服务的完整领域
跨服务的业务流程
某个通道（如Kafka主题、RabbitMQ队列等）
某个容器（数据库、缓存、队列）

生成前需收集以下信息：

资源名称与用途
版本号（新资源默认使用
```
0.0.1
```
）
消息关联关系（发送/接收的内容）
通道路由（消息流经的通道）
容器（服务读写的数据库/缓存）
适用的Schema格式（如JSON Schema、Avro、Protobuf）

如果用户指向的是代码库而非目录，则分析代码库以提取服务、消息、Schema及关联关系——然后生成对应的目录文档。

Step 3: Check the Existing Catalog

步骤3：检查现有目录

If the catalog directory already has resources, read the existing files to understand:

Naming conventions (PascalCase IDs? kebab-case?)
Folder structure (nested under domains or flat?)
Which owners/teams are already defined
Badge styles and patterns used
Schema formats in use (JSON Schema, Avro, etc.)

Match new documentation to these existing conventions.

If the user has the EventCatalog MCP server connected:

Use
```
getResources
```
to see what already exists in the catalog
Use
```
getResource
```
to check conventions used in existing entries (naming patterns, owner formats, badge styles)
Use
```
findResourcesByOwner
```
to suggest consistent ownership
Use
```
getSchemaForResource
```
to match existing schema formats

This ensures new documentation is consistent with what's already in the catalog.

如果目录中已存在资源，请读取现有文件以了解：

命名规范（ID使用大驼峰？短横线分隔？）
文件夹结构（嵌套在领域下还是扁平化？）
已定义的所有者/团队
使用的徽章样式与模式
当前采用的Schema格式（JSON Schema、Avro等）

确保新生成的文档与现有规范保持一致。

如果用户已连接EventCatalog MCP服务器：

使用
```
getResources
```
查看目录中已有的资源
使用
```
getResource
```
检查现有条目的规范（命名模式、所有者格式、徽章样式）
使用
```
findResourcesByOwner
```
建议一致的所有者信息
使用
```
getSchemaForResource
```
匹配现有的Schema格式

这能确保新文档与目录中已有的内容保持一致。

Step 4: Generate the Documentation

步骤4：生成文档

Generate files following the resource-specific references. Consult the appropriate reference file for the resource type:

```
references/services.md
```
— Services with sends/receives, channel routing, containers
```
references/events.md
```
— Events with schemas, payload examples, producer/consumer code
```
references/commands.md
```
— Commands with REST operations and schemas
```
references/queries.md
```
— Queries with REST operations and response schemas
```
references/domains.md
```
— Domains with subdomains, services, and business context
```
references/flows.md
```
— Business flows with steps, branching, and external systems
```
references/channels.md
```
— Channels with routing, protocols, and parameters
```
references/containers.md
```
— Containers (databases, caches, queues) with data classification
```
references/ubiquitous-language.md
```
— Ubiquitous language terms per domain (DDD glossary/dictionary)
```
references/teams-and-users.md
```
— Teams and users (ownership)
```
references/components.md
```
— Components (NodeGraph, Schema, Mermaid, Tabs, etc.) and resource references (
```
[[type|Name]]
```
wiki-style links)

Every resource file MUST include:

Valid YAML frontmatter between
```
---
```
delimiters
```
id
```
field matching existing catalog conventions
```
name
```
as human-readable display name
```
version
```
as semantic version string
```
summary
```
as a concise 1-2 sentence description

CRITICAL: Always use

index.mdx

as the filename for resources (services, events, commands, queries, domains, flows, channels). Teams and users use

{id}.mdx

files directly. Place files in the correct folder path following the nested structure pattern:

domains/{DomainName}/services/{ServiceName}/events/{EventName}/index.mdx

Or flat structure if the catalog uses that pattern:

services/{ServiceName}/index.mdx
events/{EventName}/index.mdx

根据资源类型对应的参考文件生成文档。请查阅对应资源类型的参考文件：

```
references/services.md
```
—— 包含发送/接收消息、通道路由、容器的服务
```
references/events.md
```
—— 包含Schema、负载示例、生产者/消费者代码的事件
```
references/commands.md
```
—— 包含REST操作与Schema的命令
```
references/queries.md
```
—— 包含REST操作与响应Schema的查询
```
references/domains.md
```
—— 包含子领域、服务及业务上下文的领域
```
references/flows.md
```
—— 包含步骤、分支与外部系统的业务流程
```
references/channels.md
```
—— 包含路由、协议与参数的通道
```
references/containers.md
```
—— 包含数据分类的容器（数据库、缓存、队列）
```
references/ubiquitous-language.md
```
—— 各领域的通用语言术语（DDD术语表/词典）
```
references/teams-and-users.md
```
—— 团队与用户（所有者信息）
```
references/components.md
```
—— 组件（NodeGraph、Schema、Mermaid、Tabs等）与资源引用（
```
[[type|Name]]
```
wiki式链接）

每个资源文件必须包含：

位于
```
---
```
分隔符之间的有效YAML frontmatter
符合现有目录规范的
```
id
```
字段
便于人类阅读的显示名称
```
name
```
语义化版本字符串格式的
```
version
```
简洁的1-2句描述
```
summary
```

重要提示：资源文件必须命名为

index.mdx

（服务、事件、命令、查询、领域、流程、通道）。团队与用户直接使用

{id}.mdx

文件。请按照嵌套结构模式将文件放置在正确的文件夹路径中：

domains/{DomainName}/services/{ServiceName}/events/{EventName}/index.mdx

如果目录采用扁平化结构，则使用以下模式：

services/{ServiceName}/index.mdx
events/{EventName}/index.mdx

Step 5: Validate the Output

步骤5：验证输出结果

Before presenting the files to the user, verify:

YAML frontmatter has
```
---
```
delimiters on both sides
All
```
id
```
fields are consistent (no spaces, match folder name)
All
```
version
```
fields are valid semver strings (e.g.,
```
0.0.1
```
)
All message references in
```
sends
```
/
```
receives
```
include
```
id
```
and optionally
```
version
```
Channel routing uses
```
to
```
/
```
from
```
fields correctly in sends/receives
Schema files referenced in
```
schemaPath
```
actually exist or are generated
```
<NodeGraph />
```
component is included for architecture visualization
Owner IDs reference real teams/users in the catalog

在向用户展示文件之前，请验证：

YAML frontmatter的首尾均有
```
---
```
分隔符
所有
```
id
```
字段保持一致（无空格，与文件夹名称匹配）
所有
```
version
```
字段均为有效的语义化版本（semver）字符串（例如：
```
0.0.1
```
）
```
sends
```
/
```
receives
```
中的所有消息引用均包含
```
id
```
，可选包含
```
version
```
通道路由在sends/receives中正确使用
```
to
```
/
```
from
```
字段
```
schemaPath
```
中引用的Schema文件确实存在或已生成
包含
```
<NodeGraph />
```
组件以实现架构可视化
所有者ID指向目录中真实存在的团队/用户

Common Patterns

常见模式

Documenting a Service That Processes Messages

记录处理消息的服务

When a user says "document my payment service that receives OrderCreated events and sends PaymentProcessed events":

Generate the service
```
index.mdx
```
with
```
receives
```
and
```
sends
```
arrays
If messages flow through channels, add
```
to
```
/
```
from
```
fields to the sends/receives
Generate each event
```
index.mdx
```
if they don't already exist in the catalog
Include
```
<NodeGraph />
```
in the service body to show message flow
Add example payload sections for each message
Place files in the correct nested folder structure

当用户提出「记录我的支付服务，该服务接收OrderCreated事件并发送PaymentProcessed事件」时：

生成包含
```
receives
```
与
```
sends
```
数组的服务
```
index.mdx
```
文件
如果消息通过通道流转，请在sends/receives中添加
```
to
```
/
```
from
```
字段
如果目录中尚未存在对应事件，请生成每个事件的
```
index.mdx
```
文件
在服务内容中包含
```
<NodeGraph />
```
组件以展示消息流转
为每个消息添加示例负载章节
将文件放置在正确的嵌套文件夹结构中

Documenting a Domain

记录领域

CRITICAL: A domain MUST have at least one service. Never create a domain without services in it. If the user describes a domain, ensure services are identified and generated for it.

When a user wants to document a full domain:

Identify the services that belong to this domain. If the user hasn't specified services, ask them: "What services belong to this domain?" Do NOT create a domain without services.
Generate the domain
```
index.mdx
```
with the
```
services
```
field listing every service
Generate each service within the domain
Generate each message referenced by the services
Generate channels if the user describes messaging infrastructure

Use the nested folder structure:

domains/{Domain}/services/{Service}/events/{Event}/

Generate a
```
ubiquitous-language.mdx
```
file for the domain by extracting domain-specific terms from service names, event/command names, entities, and business processes. Place it at
```
domains/{Domain}/ubiquitous-language.mdx
```
. See
```
references/ubiquitous-language.md
```
for format and examples.
CRITICAL: After generating all files, verify the domain's frontmatter
```
services
```
field lists every service that belongs to it. Every service created under a domain MUST be referenced in the domain's
```
index.mdx
```
:
yaml
```
services:
  - id: OrdersService
  - id: InventoryService
  - id: PaymentService
```
If a service is nested inside the domain folder but not listed in the domain's
```
services
```
frontmatter, it will not appear as part of that domain. Always cross-check.

重要提示：一个领域必须至少包含一个服务。切勿创建没有服务的领域。如果用户描述了一个领域，请确保已识别并生成对应的服务。

当用户希望记录完整领域时：

识别属于该领域的服务。如果用户未指定服务，请询问：「哪些服务属于这个领域？」切勿创建空领域。
生成包含
```
services
```
字段（列出所有服务）的领域
```
index.mdx
```
文件
生成领域下的每个服务
生成服务引用的每个消息
如果用户描述了消息基础设施，请生成对应的通道

使用嵌套文件夹结构：

domains/{Domain}/services/{Service}/events/{Event}/

从服务名称、事件/命令名称、实体及业务流程中提取领域特定术语，为该领域生成
```
ubiquitous-language.mdx
```
文件，并放置在
```
domains/{Domain}/ubiquitous-language.mdx
```
路径下。请参考
```
references/ubiquitous-language.md
```
中的格式与示例。
重要提示：生成所有文件后，请验证领域前置元数据中的
```
services
```
字段是否列出了该领域下的所有服务。所有在领域文件夹下创建的服务必须在领域的
```
index.mdx
```
中被引用：
yaml
```
services:
  - id: OrdersService
  - id: InventoryService
  - id: PaymentService
```
如果服务嵌套在领域文件夹中但未在领域的
```
services
```
前置元数据中列出，它将不会被视为该领域的一部分。请务必交叉检查。

Documenting a Business Flow

记录业务流程

When a user describes a multi-step process:

Identify distinct steps (user actions, service calls, message exchanges, external systems)
Generate the flow
```
index.mdx
```
with
```
steps
```
array
Each step should have
```
id
```
,
```
title
```
, and appropriate type (
```
actor
```
,
```
service
```
,
```
message
```
,
```
externalSystem
```
)
Connect steps with
```
next_step
```
or
```
next_steps
```
for branching

当用户描述多步骤流程时：

识别不同的步骤（用户操作、服务调用、消息交换、外部系统）
生成包含
```
steps
```
数组的流程
```
index.mdx
```
文件
每个步骤应包含
```
id
```
、
```
title
```
及对应的类型（
```
actor
```
、
```
service
```
、
```
message
```
、
```
externalSystem
```
）
使用
```
next_step
```
或
```
next_steps
```
连接步骤以支持分支

Documenting Channel Routing

记录通道路由

When a user describes how messages flow through infrastructure:

Generate channel
```
index.mdx
```
files with
```
routes
```
for channel-to-channel routing
Update service
```
sends
```
/
```
receives
```
with
```
to
```
/
```
from
```
fields pointing to channels
The full picture should show: Service A sends → Channel → routes to → Channel → Service B receives

当用户描述消息如何通过基础设施流转时：

生成包含
```
routes
```
字段（用于通道间路由）的通道
```
index.mdx
```
文件
更新服务的
```
sends
```
/
```
receives
```
字段，添加指向通道的
```
to
```
/
```
from
```
属性
完整的流转应展示为：服务A发送 → 通道 → 路由至 → 通道 → 服务B接收

Quality Checklist

质量检查清单

Take your time to do this thoroughly
Quality is more important than speed
Do not skip validation steps

Before delivering documentation to the user, verify every file against this checklist:

Frontmatter has valid YAML between
```
---
```
delimiters
```
id
```
matches the folder name
```
version
```
is a valid semver string
```
summary
```
is concise and meaningful (not generic)
Message relationships (
```
sends
```
/
```
receives
```
) include
```
id
```
Channel routing (
```
to
```
/
```
from
```
) references valid channel IDs
Body includes
```
<NodeGraph />
```
for visualization
Schema references point to real files
Folder structure follows catalog conventions
No duplicate resources (checked against existing catalog)
File is named
```
index.mdx
```
(not
```
index.md
```
,
```
README.md
```
, or anything else)
Every domain has at least one service — never create an empty domain
Domain
```
services
```
frontmatter lists every service that belongs to that domain
Every domain has a
```
ubiquitous-language.mdx
```
file with relevant domain terms extracted from services, events, commands, and business processes

请花时间仔细完成，质量优先于速度
不要跳过验证步骤

在向用户交付文档之前，请对照以下清单验证每个文件：

前置元数据在
```
---
```
分隔符之间包含有效的YAML
```
id
```
与文件夹名称匹配
```
version
```
为有效的语义化版本（semver）字符串
```
summary
```
简洁且有意义（非通用描述）
消息关联关系（
```
sends
```
/
```
receives
```
）包含
```
id
```
通道路由（
```
to
```
/
```
from
```
）引用有效的通道ID
内容中包含
```
<NodeGraph />
```
组件以实现可视化
Schema引用指向真实存在的文件
文件夹结构符合目录规范
无重复资源（与现有目录对比检查）
文件命名为
```
index.mdx
```
（而非
```
index.md
```
、
```
README.md
```
或其他名称）
每个领域至少包含一个服务——切勿创建空领域
领域的
```
services
```
前置元数据列出了该领域下的所有服务
每个领域都有
```
ubiquitous-language.mdx
```
文件，包含从服务、事件、命令及业务流程中提取的相关领域术语

Troubleshooting

故障排查

Messages Not Showing in Visualizer

消息未在可视化工具中显示

If generated events/commands don't appear in the service's node graph:

Verify the
```
sends
```
/
```
receives
```
arrays in the service frontmatter reference the exact
```
id
```
of the message
Ensure the message has its own
```
index.mdx
```
file

如果生成的事件/命令未出现在服务的节点图中：

验证服务前置元数据中的
```
sends
```
/
```
receives
```
数组是否引用了消息的准确
```
id
```
确保消息有自己的
```
index.mdx
```
文件

Schema Not Rendering

Schema未渲染

<Schema />

<SchemaViewer />

components show errors:

Verify
```
schemaPath
```
in frontmatter points to a file that exists alongside
```
index.mdx
```
Check the schema file is valid JSON/Avro/Protobuf

如果

<Schema />

或

<SchemaViewer />

组件显示错误：

验证前置元数据中的
```
schemaPath
```
是否指向与
```
index.mdx
```
同目录下的文件
检查Schema文件是否为有效的JSON/Avro/Protobuf格式

Folder Structure Not Recognized

文件夹结构未被识别

If resources don't appear in EventCatalog:

Verify the file is named exactly
```
index.mdx
```
(not
```
INDEX.mdx
```
or
```
readme.md
```
)
Verify the folder is inside a recognized collection directory (
```
services/
```
,
```
events/
```
,
```
domains/
```
, etc.)

如果资源未在EventCatalog中显示：

验证文件是否准确命名为
```
index.mdx
```
（而非
```
INDEX.mdx
```
或
```
readme.md
```
）
验证文件夹是否位于已识别的集合目录中（
```
services/
```
、
```
events/
```
、
```
domains/
```
等）

Channel Routing Not Visible

通道路由未显示

If channel connections don't appear in the visualizer:

Verify the
```
routes
```
field in the channel frontmatter references valid channel IDs
Verify the
```
to
```
/
```
from
```
fields in service sends/receives reference valid channel IDs

如果通道连接未在可视化工具中显示：

验证通道前置元数据中的
```
routes
```
字段是否引用了有效的通道ID
验证服务sends/receives中的
```
to
```
/
```
from
```
字段是否引用了有效的通道ID