使用宏
MDN 运行的 Yari 平台提供了一个宏系统,KumaScript,它使自动化某些任务成为可能。本文提供了有关如何在文章中调用 MDN 的宏的信息。
KumaScript 指南 深入介绍了如何在 MDN 上使用宏,因此本节更多的是简要概述。
宏的实现方式
MDN 上的宏使用服务器执行的 JavaScript 代码实现,使用 Node.js 解释。除此之外,我们还实现了一些库,这些库提供了服务和功能,使宏能够与平台及其内容进行交互。
在内容中使用宏
要使用宏,您需要将对宏的调用用一对双大括号括起来,并带有其参数(如果有)。
{{macroname(parameter-list)}}
关于宏调用的几点说明
- 宏名称区分大小写,但会尝试更正常见的首字母大写错误;即使宏名称在其中使用大写字母,您也可以使用全小写,并且您可以将名称通常以小写字母开头的宏的首字母大写。
- 参数用逗号隔开。
- 如果没有参数,您可以完全省略括号;
{{macroname()}}
和{{macroname}}
是相同的。 - 数值参数可以加引号,也可以不加引号。由您决定(但是,如果您有一个包含多个小数点的版本号,则需要用引号括起来)。
- 如果您遇到错误,请仔细检查代码。如果您仍然无法弄清楚发生了什么,请参阅 KumaScript 错误排查 以获得帮助。
宏被大量缓存;对于任何一组输入值(包括参数和环境值,如运行宏的 URL),结果都会被存储并重复使用。这意味着宏实际上只在输入发生变化时才会运行。
宏可以很简单,比如只插入一个较大的文本块或从 MDN 的另一个部分替换内容,也可以很复杂,比如通过搜索网站的各个部分来构建一个完整的索引,对输出进行样式化并添加链接。
您可以在 常用宏 页面上了解我们最常用的宏;您也可以浏览 所有宏的完整源代码。大多数宏源代码在开头都包含注释形式的文档。