开发工具【免费下载链接】remedaA utility library for JavaScript and TypeScript.项目地址https://gitcode.com/gh_mirrors/re/remeda点击查看免费下载本篇指南讲解 RemedaJavaScript/TypeScript 工具库文档站中Mapping迁移对照文档的编写规范从文件放置位置、frontmatter 元数据到标题层级、正文写法与代码示例组织方式。读完你将掌握如何为 lodash、Ramda、just 等第三方库的每个函数撰写一条格式正确、能被文档站正确渲染并进入检索体系的对照条目同时了解背后的 Astro 内容集合Content Collection加载与渲染机制。Mapping 文档是什么Remeda 文档站的迁移对照层Remeda 是一个面向 JavaScript 与 TypeScript 的工具库其文档站点位于仓库的 packages/docs 目录采用 Astro 构建。在文档站中除了面向 Remeda 自身 API 的函数文档functions 集合之外还存在一套独立的mapping 集合迁移对照集合为 lodash、Ramda、just 等流行库的每个函数给出该函数对应 Remeda 的哪个 API、存在哪些行为差异、如何改写的对照说明帮助从其他函数库迁移到 Remeda 的开发者快速定位替代方案。该集合的约定分散在两处一是 packages/docs/src/content/mapping/content.config.ts 中定义的加载器与 schema决定文件如何被发现、元数据如何校验二是仓库根目录下 .claude/rules/content-mapping.md 这份规则文档决定条目正文如何书写。本文将以这份规则文档为核心结合集合定义、渲染组件与大量既有条目完整还原 Mapping 文档的编写规范。文件布局库目录即命名空间文件名即函数名Mapping 文档以 Markdown 文件形式存放在packages/docs/src/content/mapping/library/目录下每个库一个子目录。当前仓库中已存在三个库的对照目录packages/docs/src/content/mapping/lodashlodash 函数对照条目最多按 Array、Math、Object、String、Util、Function 等分类组织packages/docs/src/content/mapping/ramdaRamda 函数对照packages/docs/src/content/mapping/justjust 函数对照。文件名的约束由 mapping/content.config.ts 中的globloader 决定export const mappingCollection defineCollection({ loader: glob({ base: import.meta.dirname, pattern: **/[^_]*.md, // We treat the file name as the function name, and function names are case- // sensitive, but the default ID generator lowers the case. generateId: ({ entry }) entry.replace(/\.md$/, ), }), // ... });文件名即函数名例如 packages/docs/src/content/mapping/lodash/camelCase.md 表示对照 lodash 的camelCasepackages/docs/src/content/mapping/just/has.md 表示对照 just 的has大小写敏感loader 特意覆盖了默认的 ID 生成器默认会把 ID 转为小写因为函数名区分大小写camelCase与camercase不能被合并以_开头的文件被排除在内容集合之外pattern: **/[^_]*.md保证__MISSING.md、___TODO.md这类工作文档不会被当成正式条目加载ID 结构固定为「库名/函数名」两层工具函数 libraries.ts 遍历全部条目通过 invariant 断言每个 ID 都必须位于库目录之下hasAtLeast(parts, 2)且不允许出现更深层级的子目录parts.length 2否则直接抛错。frontmattercategory与remeda两个必填字段每个 Mapping 文档的 frontmatter 由 content.config.ts 中的 zod schema 严格校验.strict()意味着出现未知字段会被拒绝schema: z .object({ category: z.string().min(1), remeda: reference(functionsCollectionName).optional(), }) .strict() .readonly(),category必填非空字符串该函数在源库中归属的分类例如 lodash/add.md 的category: Math、lodash/assign.md 的category: Object、just/has.md 的category: Objects。分类会被用于页面上的分组与侧边导航见下文渲染链路remeda可选对 Remeda 自身 functions 集合即 functions/content.config.ts 中通过 TypeDoc 从remeda/src/index.ts生成的 API 文档的交叉引用。填写后条目卡片顶部会渲染一个指向对应 Remeda 函数文档的跳转链接留空则意味着 Remeda 目前没有直接对应的函数这类条目会在页面上以候选状态展示见下文特殊文件与候选机制。一个最小的合法条目甚至可以不写正文、只有 frontmatter例如 lodash/cond.md--- category: Util remeda: conditional ---标题层级规则正文子标题必须从####h4开始这是 .claude/rules/content-mapping.md 中唯一一条直接规定写作格式的规则也是本篇最核心的约定Body sub-headings start at####(h4) — entries render inside anarticlewhose function name is theh3即条目正文中的子标题从####起跳不允许使用##或###。原因在于渲染结构——每个映射条目不是以独立的整页 HTML 文档呈现而是被渲染成一张「卡片card」卡片内已经有了两层标题占用函数名标题是h3由 h3-card-title.tsx 中的H3CardTitle组件渲染它通过CardTitle asChild把标题元素强制固定为h3卡片的语义容器是article由 article-card.tsx 中的ArticleCard组件渲染Card asChild将外层元素固定为article正文通过 Prose 组件挂载到卡片内。如果正文里再出现###就会和函数名的h3平级甚至产生层级混乱破坏articleh3→ 正文子标题h4的语义嵌套。因此写作条目正文时若需要分小节一律使用####。从既有的高质量条目中可以看到这一规则的实际运用例如 lodash/camelCase.md 用#### Simple strings、#### Normalized、#### Missing input三个 h4 小节组织不同场景lodash/debounce.md 用#### Reference、#### With call arguments、#### With cached value组织三种复杂度的参考实现。正文写法差异优先的条目化说明 双栏代码对照Mapping 条目的正文不是 Remeda API 的复述而是聚焦「从源库迁移到 Remeda 时需要知道的差异」。其标准写作模式可归纳为差异要点列表 场景化代码对照行为差异用无序列表逐条列出每个差异点单独成一条 bullet直截了当地指出Lodash 怎么做 / Remeda 怎么做。以 lodash/camelCase.md 为例它列出四条差异分词策略不同Lodash 尝试伪语言学分词pseudo-linguistic word splitting来处理特殊字符结果可能不准确Remeda 采用基于 type-fest 定义的更简单分词方案仅适用于标识符、内部 key 等简单字符串涉及语言与区域敏感的文本处理应改用原生Intl.Segmenter连续大写处理不同Remeda 对连续大写字符的处理与 Lodash 不同需要传第二个参数{ preserveConsecutiveUppercase: false }才能得到与 Lodash 一致的结果归一化normalization缺失Lodash 在分词前会执行deburr、移除撇号等归一化见 lodash/deburr.mdRemeda 分词更简单、不含这些归一化需要时需手动处理入参边界不同Lodash 允许无参调用或传入undefinedRemeda 不支持需在调用前自行兜底。再如 lodash/assign.md差异点聚焦在**可变性mutability与可变参数variadic**两个维度Lodash 的assign是就地合并直接修改第一个入参Remeda 的merge/mergeAll总是返回新对象绝不改动任何输入对象Lodash 的assign接受任意数量的参数Remeda 中合并两个对象用merge合并两个以上对象改用接收对象数组的mergeAll。just/has.md 则直接点出 API 能力差距just 的has支持深层路径如[a, b]、a.b而 Remeda 的hasProp只检查单层 key。代码示例采用源库写法 → Remeda 写法的双栏对照正文中的代码统一用 fenced code block并严格标注注释前缀区分两侧。最简单的形式如 lodash/compact.md// Lodash compact(DATA); // Remeda filter(DATA, isTruthy);复杂场景则按差异拆成多个 h4 小节分别给出可运行片段。仍以 camelCase 为例#### Simple strings给出直译写法// Lodash _.camelCase(input); // Remeda toCamelCase(input, { preserveConsecutiveUppercase: false });#### Normalized给出Remeda 原生 API的等价还原先normalize(NFD)提升变音符号为独立字符再用正则剔除撇号与独立变音字符// Lodash _.camelCase(input); // Remeda Native toCamelCase( input // Promote diacritics to be independent characters in the string. .normalize(NFD) // Remove apostrophes and all independent diacritic characters. .replace(/[\u2019\u0300-\u036f]/g, ), { preserveConsecutiveUppercase: false }, );#### Missing input给出入参兜底的两种等价写法显式条件分支或?? 合并。这种逐差异小节 可复制代码的结构正是 Mapping 条目正文的标准形态。特殊条目的写法deburr与 Lodash 文档内锚点Mapping 正文中引用同库其他条目时原文档内使用锚点链接如 camelCase 正文中的deburr。在仓库内它们对应packages/docs/src/content/mapping/lodash/deburr.md这一实际文件交叉引用 Remeda 自身 API 时同样使用锚点形式如 assign 正文中的mergeAll其实现位于 packages/remeda/src/mergeAll.ts。撰写新条目时应保持这种以函数名作锚点的引用习惯使文档站页面内跳转与仓库文件结构一一对应。渲染链路一个条目如何变成页面上的卡片Mapping 文档最终通过 packages/docs/src/pages/migrate/[library].astro 渲染成/migrate/library静态页面。整条渲染管线如下getStaticPaths调用 libraries.ts 的getAllMappedLibraries从内容集合中推导出所有库名lodash、ramda、just为每个库生成一个页面页面主体调用 entries.ts 的getMigrationMappings(library)先按id过滤出该库的全部条目用sortBy按字典序忽略大小写排序再用groupBy按 frontmatter 的category分组最后经 sort-categories.ts 排序——其中Deprecated分类被强制排到末尾其余分类按字母序排列每个分类渲染为一个 docs-section.astro 区块其h2仅作屏幕阅读器标签sr-only区块内每个条目渲染为一个 mapping-function-card.astro 卡片MappingFunctionCard组装卡片内容函数名h3、右侧查看源库文档外链按钮、分类 Badge、编辑链接以及 frontmatter 中remeda引用对应的函数跳转正文非空时才通过Prose渲染 Markdown 内容。函数名指向源库官方文档的 URL 由 urls.ts 的mappingUrl按库生成lodash →https://lodash.com/docs/4.17.15#nameramda →https://ramdajs.com/docs/#namejust →https://anguscroll.com/just/just-name。从这链路可以推断category 字段不仅决定页面分组还决定导航结构——entries.ts 的forNavbar会把「分类 → 条目函数名」的映射转成侧边导航条目供 docs-page.astro 布局使用。特殊文件与候选机制__MISSING、___TODO与未提供函数mapping 目录中还包含两类被 loader 排除[^_]*模式的工作文档它们不属于正式条目但反映了规范背后的维护流程lodash/__MISSING.mdlodash 中尚未建立映射的函数清单按 Array / Date / Function / Lang / Number / Object / Seq / Util / String 分组罗列如fill、chain、thru、stubArray等String 组已标注完成。该文件开头的 TODO 指向 You-Dont-Need-Lodash-Underscore 这一参考来源说明清单主要用于评估这些函数是否需要补写对照lodash/___TODO.md记录 Mapping 体系的待办与决策方向其中与写作规范直接相关的有lodash 的 collection 组函数实为「数组/对象混合」函数需要给出通用引导主要建议使用valueslodash 多数数据入参接受null | undefined而 Remeda 不接受lodash 的iteratee通常只接收一个参数而 Remeda 通常接收三个参数index、data等。此外对于Remeda 未提供对应函数的条目TODO 中提出引入特殊标记如candidate: true来渲染鼓励用户提交使用场景的横幅并点名pad、padStart、padEnd、parseInt、repeat、replace等候选函数——从源码结构看该机制在写作规范中对应frontmatter 中remeda字段留空这一状态MappingFunctionCard对此已有相应的无跳转链接渲染分支。实操编写一条 Mapping 文档的完整步骤综合以上规范在 Remeda 仓库中新增一条映射条目的标准流程是确定目标库与函数创建文件packages/docs/src/content/mapping/library/函数名.md函数名保持与源库一致的大小写填写 frontmattercategory使用源库中的函数分类如 lodash 的Math、Object、String、Util若 Remeda 有对应实现在remeda字段引用该函数例如remeda: toCamelCase无对应实现则留空正文第一层小标题一律从####开始h3 已被函数名占用先用无序列表逐条罗列与源库的行为差异可变性、参数边界、分词/归一化策略、类型差异等为每个差异配一个 fenced code block以// Lodash/// Remeda必要时// Remeda Native注释区分两侧写法代码需可复制运行若 Remeda 没有直接对应函数给出基于现有 API如filterisTruthy还原compact的组合替代方案或引用funnel等工具的组合实现参见 lodash/debounce.md 中基于funnel的 debounce 参考实现其完整版位于 packages/remeda/src/funnel.lodash-debounce.test.ts 与 packages/remeda/src/funnel.lodash-debounce-with-cached-value.test.ts可整段复制不要使用##/###、不要添加 schema 之外的 frontmatter 字段、不要改变文件命名大小写否则会被 loader 排除或 zod 校验拒绝。结语Mapping 文档是 Remeda 文档站中连接第三方函数库与 Remeda API 的桥梁层。它的写作规范可以浓缩为两句话frontmatter 严格二字段categoryremeda、文件名即函数名正文标题从 h4 起跳、以差异列表 双栏代码为骨架。这两条约定分别由 content.config.ts 的 zod schema 与 .claude/rules/content-mapping.md 规则文档固化并由 mapping-function-card.astro 等组件在渲染时兑现。对贡献者而言参考 lodash/camelCase.md差异拆解范本、lodash/debounce.md复杂参考实现范本与 lodash/assign.md语义差异范本三份既有条目即可快速写出符合规范、可被正确渲染和检索的迁移对照文档。赞分享开发工具【免费下载链接】remedaA utility library for JavaScript and TypeScript.项目地址https://gitcode.com/gh_mirrors/re/remeda点击查看免费下载相关推荐Incus 文档写作语法速查表Markdown 与 MyST 混排的 Sphinx 文档编写规范Incus 文档写作语法速查表Markdown 与 MyST 混排的 Sphinx 文档编写规范 Incus 项目的官方文档 doc https://lin后端虚拟化容器运行时Livewire 文档写作规范官方 docs 编写规则与源码实现对照指南Livewire 文档写作规范官方 docs 编写规则与源码实现对照指南 本篇技术指南基于 Livewire 仓库内实际生效的文档编写规范 .claude/后端前端GoReleaser 文档编写规范基于 Hugo 站点的技术文档作者指南GoReleaser 文档编写规范基于 Hugo 站点的技术文档作者指南 本文以仓库内 .copilot/skills/authoring docs/SKIL开发工具CI/CD构建工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
