Medusa 文档写作规范指南Vale 与 ESLint 规则体系全解析【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa本篇指南围绕 Medusa 开源仓库中的文档规范文件 vale-rules.md 展开系统讲解 Medusa 官方文档写作必须遵守的 Vale 与 ESLint 规则涵盖人称、语态、术语、标点、代码格式与句子长度等全部维度。读完本篇读者可以掌握 Medusa 文档的完整写作约束了解每条规则背后的自动化检查实现规则文件位于 www/vale/styles/docs并能够在写作前按照官方清单完成自查写出能够通过 CI 校验、风格统一、便于搜索引擎与 Agent 解析的文档内容。规则体系概览Vale 与 lint:content 双通道校验Medusa 文档采用两套自动化工具共同保证文本质量Vale基于www/vale/目录下的规则集运行负责自然语言层面的风格检查例如人称、被动语态、句子长度、术语替换等。运行脚本见 run-vale.sh它接收应用路径与告警级别参数将www/apps/$1下的内容目录拼成文件列表后调用vale --minAlertLevel执行检查。ESLintlint:content负责代码与格式层面的约束例如代码行长、MDX 代码块语言标签等。lint:content脚本定义在 www/package.json 中通过turbo run lint:content触发对所有文档应用book、user-guide、cloud 等生效。两条规则要求所有文档必须全部通过违反任意一条都会导致文档无法合入。下面逐条拆解每条规则的具体内容、正反例与底层实现。第一人称禁令只用你不用我们规则严禁使用第一人称复数first-person plural。文档正文中不得出现we、us、lets、our等词。原因在于文档面向单个读者使用你或祈使句能够给出更直接、更易执行的指引。官方给出的正反例❌ We recommend using workflows for all mutations. ❌ Lets create a workflow. ❌ Our platform supports... ❌ Us, weve, were ✅ Use workflows for all mutations. ✅ Create a workflow. ✅ The platform supports... ✅ You can configure...唯一例外是US美国这一国家缩写。底层实现见 We.yml它通过existence类型规则以ignorecase: true匹配we、weve、were、us、lets并在exceptions中放行USOur.yml 负责拦截our与ours。此外 FirstPerson.yml 还拦截单数第一人称I、Id、Ill、Im、Ive、me、my、mine三者配合确保全文不出现任何第一人称视角。被动语态改写成主动规则Vale 对被动语态发出告警必须改写为主动语态。需要特别留意can be 过去分词结构应改写为you can 动词。❌ The workflow is created by calling createWorkflow. ❌ Products are fetched from the database. ❌ The configuration has been updated. ❌ Custom domains can be configured in the settings. ✅ Call createWorkflow to create a workflow. ✅ The service fetches products from the database. ✅ Update the configuration. ✅ You can configure custom domains in the settings.实现层面Passive.yml 使用raw字段匹配am|are|were|being|is|been|was|be等系动词后紧跟过去分词的组合tokens中内置了从awoken到written的数百个不规则动词过去分词覆盖 built、broken、made、run、set、shown 等常见词以降低漏检率。术语规范Backend 与 API 的边界规则指代 Medusa 服务器/应用本身时必须使用 backend严禁用 API 作为 Medusa backend 的同义词。❌ Serve your Medusa API. ❌ Connect the storefront to the Medusa API. ❌ The Medusa API handles the requests. ✅ Serve your Medusa backend. ✅ Connect the storefront to the Medusa backend. ✅ The Medusa backend handles the requests.同时规则也明确了边界当特指某条 API 路由或端点时API 依然是正确用法例如 call the Products API、the Admin API。也就是说backend指代服务本身API指代具体的接口资源二者不可混用。这一区分与 Medusa 的分层架构一致packages/medusa/src/api目录存放全部 HTTP 路由实现而服务端整体由packages/medusa/src中的模块、加载器、策略等共同构成。Medusa Cloud 命名根据语境二选一规则任何情况下都不要写 Medusa Cloud根据语境使用简化形式将产品/平台作为名词指代时使用Medusa将平台作为地点或服务指代例如部署到该平台时使用Cloud。❌ Medusa Cloud allows you to deploy your application. ✅ Medusa allows you to deploy your application. ❌ Deploy your project to Medusa Cloud. ✅ Deploy your project to Cloud. ❌ The Medusa Cloud dashboard shows your deployments. ✅ The Cloud dashboard shows your deployments.这条规则的意图是避免冗长的品牌全称同时让产品本身与托管部署地两种语义在行文中自然区分。拉丁缩写不用 e.g.写 for example规则严禁使用e.g.,一律改写为for example。❌ Use a workflow step, e.g., to call an external API. ✅ Use a workflow step, for example, to call an external API.类似的简写处理思路在规则集中保持一致文档面向国际开发者与翻译流程使用完整英文单词比拉丁缩写更容易理解和本地化。破折号禁止使用 Em Dash规则严禁使用破折号em dash即—。通过改写句子结构来避免通常可以用逗号、括号或重新断句替代❌ The workflow runs the steps — in order — and compensates on failure. ✅ The workflow runs the steps in order and compensates on failure. ❌ Use createStep — not direct service calls — for mutations. ✅ Use createStep, not direct service calls, for mutations.问题词汇表删掉空话副词规则Vale 会标记以下问题词汇写作时应避免使用通常直接删除即可。AvoidUse insteadsimply(remove it)just(remove it)easy(remove it)straightforward(remove it)obviously(remove it)basically(remove it)这些词大多属于填充性副词删去后句子更精确、更可信。与之配套的还有 Wordiness.yml 中的替换规则例如in order to改写为to、due to the fact that改写为because、has the ability to改写为can、whether or not改写为whetherTerms.yml 则规定e-commerce一律改写为ecommerce。另外 YouCan.yml 会针对you can发出告警提示考虑用更直接的说法与前面多用祈使句的风格取向呼应。代码行长限制单行不超过 64 字符规则代码行必须小于等于 64 个字符由lint:content强制检查。该规则适用于 MDX 文件内的代码块长行必须手动换行// ❌ Too long import { createWorkflow, WorkflowResponse, createStep, StepResponse } from medusajs/framework/workflows-sdk // ✅ Break imports import { createWorkflow, WorkflowResponse, createStep, StepResponse, } from medusajs/framework/workflows-sdk这一限制保证了文档代码块在窄屏渲染与复制场景下不出现横向滚动也让行内 diff 更易读。Medusa 文档中大量涉及 workflows-sdk 的示例代码导入语句较长时尤其需要注意拆分。语言标签非 JSX 一律用 ts规则Vale 对 TypeScript 代码块使用tsx 发出告警应使用ts❌ tsx ✅ ts仅当内容是包含 JSX 的 React 组件文件时才允许使用tsx。底层实现见 [TypeScript.yml](https://link.gitcode.com/i/6a03cf93deed7f4c74e72a7a95a98eea)它以 raw 作用域匹配 tsx标记。Medusa 仓库中的源码大量使用.tsx 扩展名例如 packages/admin/dashboard/src 下的 React 组件但文档示例中展示纯逻辑代码时应去掉 JSX 语义的标签。URL 格式正文禁用裸链接规则正文文字中严禁出现裸 URL必须使用 Markdown 链接格式。❌ Visit https://docs.medusajs.com for more information. ✅ Visit the [Medusa documentation](https://docs.medusajs.com) for more information.裸 URL 在渲染、翻译和链接检查流程中都容易失效统一使用label可以让读者从链接文字预判目标内容也便于后续的链接有效性校验。句子长度控制在 30 词以内规则保持句子简洁Vale 建议单句不超过约 30 个单词。过长的复合句需要拆分。❌ The Product Module is a standalone package that provides product management features and integrates with the Cart Module to allow adding products to carts, which then connects to the Order Module for order management. ✅ The Product Module is a standalone package that provides product management features. It integrates with the Cart Module to allow adding products to carts.底层实现见 SentenceLength.yml采用occurrence类型规则max: 30以\b(\w)\b统计句内单词数并给出 suggestion 级别提示。较长的术语如 Module 名称会计入单词数因此写作时要主动把长句拆成多句。仓库中 www/vale/styles/docs 还包含 ComplexWords、Ordinal、Contractions、OxfordComma、Spacing、Acronyms、Gender 等更多风格规则共同构成完整的英文文档风格检查集。提交前自查清单在写作时脑内运行校验vale-rules.md 最后给出了一份写作前的自查清单官方建议在落笔写任何正文前逐项核对出现 we、us、lets、our 时替换为 you 或祈使句出现被动语态包括 can be configured、is created 等时改写为主动you can configure、call X to create出现 simply、just、easy 等词时删除代码行超过 64 字符时换行裸 URL 用label包裹非 JSX 的 TypeScript 代码块把tsx 改为ts用 Medusa API 指代 backend 时替换为 Medusa backend出现 Medusa Cloud 时替换为 Medusa名词形式或 Cloud地点/服务形式出现e.g.,时替换为for example出现破折号—时改写句子去除将这份清单内化为写作习惯可以在提交文档前提前消除绝大多数 CI 告警。若需在本地验证可在 www 目录通过yarn lint:content定义见 www/package.json运行 ESLint 内容检查并使用 run-vale.sh 指定应用路径与告警级别运行 Vale规则词汇表可查看 accept.txt 与 reject.txt前者放行 Qovery、Netlify、s3、vite 等专有名词的拼写告警。小结Medusa 的文档写作规范以 Vale 规则集 lint:content双通道落地覆盖人称、语态、术语、标点、措辞、代码格式与句子长度七个层面。每条规则都不是孤立的建议而是在 www/vale/styles/docs 中有对应 YAML 实现的强制约束并由 CI 自动校验。遵循这套规范写出的文档不仅风格统一、易于阅读也更容易被翻译、搜索引擎与 LLM 准确解析与引用。【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Medusa 文档写作规范指南Vale 与 ESLint 规则体系全解析【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa本篇指南围绕 Medusa 开源仓库中的文档规范文件 vale-rules.md 展开系统讲解 Medusa 官方文档写作必须遵守的 Vale 与 ESLint 规则涵盖人称、语态、术语、标点、代码格式与句子长度等全部维度。读完本篇读者可以掌握 Medusa 文档的完整写作约束了解每条规则背后的自动化检查实现规则文件位于 www/vale/styles/docs并能够在写作前按照官方清单完成自查写出能够通过 CI 校验、风格统一、便于搜索引擎与 Agent 解析的文档内容。规则体系概览Vale 与 lint:content 双通道校验Medusa 文档采用两套自动化工具共同保证文本质量Vale基于www/vale/目录下的规则集运行负责自然语言层面的风格检查例如人称、被动语态、句子长度、术语替换等。运行脚本见 run-vale.sh它接收应用路径与告警级别参数将www/apps/$1下的内容目录拼成文件列表后调用vale --minAlertLevel执行检查。ESLintlint:content负责代码与格式层面的约束例如代码行长、MDX 代码块语言标签等。lint:content脚本定义在 www/package.json 中通过turbo run lint:content触发对所有文档应用book、user-guide、cloud 等生效。两条规则要求所有文档必须全部通过违反任意一条都会导致文档无法合入。下面逐条拆解每条规则的具体内容、正反例与底层实现。第一人称禁令只用你不用我们规则严禁使用第一人称复数first-person plural。文档正文中不得出现we、us、lets、our等词。原因在于文档面向单个读者使用你或祈使句能够给出更直接、更易执行的指引。官方给出的正反例❌ We recommend using workflows for all mutations. ❌ Lets create a workflow. ❌ Our platform supports... ❌ Us, weve, were ✅ Use workflows for all mutations. ✅ Create a workflow. ✅ The platform supports... ✅ You can configure...唯一例外是US美国这一国家缩写。底层实现见 We.yml它通过existence类型规则以ignorecase: true匹配we、weve、were、us、lets并在exceptions中放行USOur.yml 负责拦截our与ours。此外 FirstPerson.yml 还拦截单数第一人称I、Id、Ill、Im、Ive、me、my、mine三者配合确保全文不出现任何第一人称视角。被动语态改写成主动规则Vale 对被动语态发出告警必须改写为主动语态。需要特别留意can be 过去分词结构应改写为you can 动词。❌ The workflow is created by calling createWorkflow. ❌ Products are fetched from the database. ❌ The configuration has been updated. ❌ Custom domains can be configured in the settings. ✅ Call createWorkflow to create a workflow. ✅ The service fetches products from the database. ✅ Update the configuration. ✅ You can configure custom domains in the settings.实现层面Passive.yml 使用raw字段匹配am|are|were|being|is|been|was|be等系动词后紧跟过去分词的组合tokens中内置了从awoken到written的数百个不规则动词过去分词覆盖 built、broken、made、run、set、shown 等常见词以降低漏检率。术语规范Backend 与 API 的边界规则指代 Medusa 服务器/应用本身时必须使用 backend严禁用 API 作为 Medusa backend 的同义词。❌ Serve your Medusa API. ❌ Connect the storefront to the Medusa API. ❌ The Medusa API handles the requests. ✅ Serve your Medusa backend. ✅ Connect the storefront to the Medusa backend. ✅ The Medusa backend handles the requests.同时规则也明确了边界当特指某条 API 路由或端点时API 依然是正确用法例如 call the Products API、the Admin API。也就是说backend指代服务本身API指代具体的接口资源二者不可混用。这一区分与 Medusa 的分层架构一致packages/medusa/src/api目录存放全部 HTTP 路由实现而服务端整体由packages/medusa/src中的模块、加载器、策略等共同构成。Medusa Cloud 命名根据语境二选一规则任何情况下都不要写 Medusa Cloud根据语境使用简化形式将产品/平台作为名词指代时使用Medusa将平台作为地点或服务指代例如部署到该平台时使用Cloud。❌ Medusa Cloud allows you to deploy your application. ✅ Medusa allows you to deploy your application. ❌ Deploy your project to Medusa Cloud. ✅ Deploy your project to Cloud. ❌ The Medusa Cloud dashboard shows your deployments. ✅ The Cloud dashboard shows your deployments.这条规则的意图是避免冗长的品牌全称同时让产品本身与托管部署地两种语义在行文中自然区分。拉丁缩写不用 e.g.写 for example规则严禁使用e.g.,一律改写为for example。❌ Use a workflow step, e.g., to call an external API. ✅ Use a workflow step, for example, to call an external API.类似的简写处理思路在规则集中保持一致文档面向国际开发者与翻译流程使用完整英文单词比拉丁缩写更容易理解和本地化。破折号禁止使用 Em Dash规则严禁使用破折号em dash即—。通过改写句子结构来避免通常可以用逗号、括号或重新断句替代❌ The workflow runs the steps — in order — and compensates on failure. ✅ The workflow runs the steps in order and compensates on failure. ❌ Use createStep — not direct service calls — for mutations. ✅ Use createStep, not direct service calls, for mutations.问题词汇表删掉空话副词规则Vale 会标记以下问题词汇写作时应避免使用通常直接删除即可。AvoidUse insteadsimply(remove it)just(remove it)easy(remove it)straightforward(remove it)obviously(remove it)basically(remove it)这些词大多属于填充性副词删去后句子更精确、更可信。与之配套的还有 Wordiness.yml 中的替换规则例如in order to改写为to、due to the fact that改写为because、has the ability to改写为can、whether or not改写为whetherTerms.yml 则规定e-commerce一律改写为ecommerce。另外 YouCan.yml 会针对you can发出告警提示考虑用更直接的说法与前面多用祈使句的风格取向呼应。代码行长限制单行不超过 64 字符规则代码行必须小于等于 64 个字符由lint:content强制检查。该规则适用于 MDX 文件内的代码块长行必须手动换行// ❌ Too long import { createWorkflow, WorkflowResponse, createStep, StepResponse } from medusajs/framework/workflows-sdk // ✅ Break imports import { createWorkflow, WorkflowResponse, createStep, StepResponse, } from medusajs/framework/workflows-sdk这一限制保证了文档代码块在窄屏渲染与复制场景下不出现横向滚动也让行内 diff 更易读。Medusa 文档中大量涉及 workflows-sdk 的示例代码导入语句较长时尤其需要注意拆分。语言标签非 JSX 一律用 ts规则Vale 对 TypeScript 代码块使用tsx 发出告警应使用ts❌ tsx ✅ ts仅当内容是包含 JSX 的 React 组件文件时才允许使用tsx。底层实现见 [TypeScript.yml](https://link.gitcode.com/i/6a03cf93deed7f4c74e72a7a95a98eea)它以 raw 作用域匹配 tsx标记。Medusa 仓库中的源码大量使用.tsx 扩展名例如 packages/admin/dashboard/src 下的 React 组件但文档示例中展示纯逻辑代码时应去掉 JSX 语义的标签。URL 格式正文禁用裸链接规则正文文字中严禁出现裸 URL必须使用 Markdown 链接格式。❌ Visit https://docs.medusajs.com for more information. ✅ Visit the [Medusa documentation](https://docs.medusajs.com) for more information.裸 URL 在渲染、翻译和链接检查流程中都容易失效统一使用label可以让读者从链接文字预判目标内容也便于后续的链接有效性校验。句子长度控制在 30 词以内规则保持句子简洁Vale 建议单句不超过约 30 个单词。过长的复合句需要拆分。❌ The Product Module is a standalone package that provides product management features and integrates with the Cart Module to allow adding products to carts, which then connects to the Order Module for order management. ✅ The Product Module is a standalone package that provides product management features. It integrates with the Cart Module to allow adding products to carts.底层实现见 SentenceLength.yml采用occurrence类型规则max: 30以\b(\w)\b统计句内单词数并给出 suggestion 级别提示。较长的术语如 Module 名称会计入单词数因此写作时要主动把长句拆成多句。仓库中 www/vale/styles/docs 还包含 ComplexWords、Ordinal、Contractions、OxfordComma、Spacing、Acronyms、Gender 等更多风格规则共同构成完整的英文文档风格检查集。提交前自查清单在写作时脑内运行校验vale-rules.md 最后给出了一份写作前的自查清单官方建议在落笔写任何正文前逐项核对出现 we、us、lets、our 时替换为 you 或祈使句出现被动语态包括 can be configured、is created 等时改写为主动you can configure、call X to create出现 simply、just、easy 等词时删除代码行超过 64 字符时换行裸 URL 用label包裹非 JSX 的 TypeScript 代码块把tsx 改为ts用 Medusa API 指代 backend 时替换为 Medusa backend出现 Medusa Cloud 时替换为 Medusa名词形式或 Cloud地点/服务形式出现e.g.,时替换为for example出现破折号—时改写句子去除将这份清单内化为写作习惯可以在提交文档前提前消除绝大多数 CI 告警。若需在本地验证可在 www 目录通过yarn lint:content定义见 www/package.json运行 ESLint 内容检查并使用 run-vale.sh 指定应用路径与告警级别运行 Vale规则词汇表可查看 accept.txt 与 reject.txt前者放行 Qovery、Netlify、s3、vite 等专有名词的拼写告警。小结Medusa 的文档写作规范以 Vale 规则集 lint:content双通道落地覆盖人称、语态、术语、标点、措辞、代码格式与句子长度七个层面。每条规则都不是孤立的建议而是在 www/vale/styles/docs 中有对应 YAML 实现的强制约束并由 CI 自动校验。遵循这套规范写出的文档不仅风格统一、易于阅读也更容易被翻译、搜索引擎与 LLM 准确解析与引用。【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
