Macros

Kuma 平台为 MDN 提供了强大的宏系统——KumaScript,使得 MDN 能够自动地去做各种东西。本文提供一些信息以便大家知道如何使用 MDN 上的文章内的宏。

鉴于本文只是 KumaScript 的简介,KumaScript 指南提供了更深入的内容。

宏是如何实现的

MDN使用的Macros(宏)是基于Node.js执行环境,并在服务端执行运行。这里包括了大量的代码库,另外对此还提供了丰富的wiki说明文档内容。如果你希望能学习到更多的内容,可以查看 KumaScript 指南KumaScript reference 则提供了更多关于这些代码库和KumaScript的API的实现机理。

在文章中使用宏

要实际使用宏,只需将对宏的调用括在一对双括号中,其参数(如果有)括在括号中;如下:

{{macroname(parameter-list)}}

关于宏调用的一些注意事项:

  • 宏名称区分大小写,但有些尝试是为了纠正常见的大写错误;即使宏名称在其中使用大写,您也可以使用全部小写,并且您可以将名称通常以小写字母开头的宏大写。
  • 参数以逗号分隔
  • 如果没有参数,您可以完全省略括号; {{macroname()}}{{macroname}} 完全相同。
  • 数字参数可以是引号,也可以不是。这取决于您(但是,如果您的版本号中包含多个小数,则需要在引号中)
  • 如果您遇到错误,请仔细检查您的代码。如果仍然无法弄清楚发生了什么,请参阅Troubleshooting KumaScript errors以获取帮助。

宏被高度缓存;对于任何一组输入值(参数和环境值,例如运行宏的URL),结果都会被存储和重用。这意味着宏仅在输入发生变化时才实际运行。

注意: 您可以通过在浏览器中强制刷新页面(即转移重新加载)来强制重新评估页面上的所有宏。

宏可以像插入更大的文本块或从MDN的另一部分交换内容一样简单,也可以通过搜索站点的各个部分,设置输出样式和添加链接来构建整个内容索引。

您可以在Commonly-used macros页面上阅读我们最常用的宏;另外,这里有complete list of all macros。大多数宏都有内置的文档,作为顶部的注释。