MCBBS Wiki:模板文档页模式

Salt lovely留言 | 贡献2022年10月4日 (二) 19:36的版本 (创建页面,内容为“'''模板文档页模式'''是一种编写模板文档的方式,主要过程是将模板的文档放置在模板的子页面中。 这个模式可以将模板与其文档隔离开,编辑模板或编辑文档的工作互不干扰;比如一些模板需要添加保护,而文档可能又需要大家共同编写,此时将模板与文档分开到两个页面,就可以分别设置保护等级,分开维护了。 == 为什么使用这种模式 == 最早…”)
(差异) ←上一版本 | 最后版本 (差异) | 下一版本→ (差异)

模板文档页模式是一种编写模板文档的方式,主要过程是将模板的文档放置在模板的子页面中。

这个模式可以将模板与其文档隔离开,编辑模板或编辑文档的工作互不干扰;比如一些模板需要添加保护,而文档可能又需要大家共同编写,此时将模板与文档分开到两个页面,就可以分别设置保护等级,分开维护了。

为什么使用这种模式

最早的文档是与模板代码放在一起,写在模板页面上的<noinclude>标签中。

除了解决上述问题外,模板文档页模式还有以下优点:

  1. (对于高频使用的模板而言)可以节省服务器开销,因为文档并不属于模板本身,编辑文档并不会让使用该模板的页面刷新。
  2. (对于使用模板的用户而言)可以节省注意力,与模板分离的文档可以长期迭代,添加参数说明、示例、分类等内容帮助使用者理解模板。
  3. (对于编辑模板或文档的用户而言)可以专注于模板或文档的编写,不用在编辑栏中同时面对模板与文档两种风格迥异的代码。
  4. (对于管理维护模板的工作而言)可以降低模板与文档的维护成本,比如管理员可以锁定“热门”模板,但同时允许用户自由编辑该模板的文档。

与这种模式增加的工作量相比,它的优势十分明显,因此许多MediaWiki网站使用这个模式编写模板文档(以及模块文档、微件文档)。

实践方法

详细流程可以查看{{Documentation}}的文档,这里仅给出最简单的实践方法。

<noinclude>{{doc}}</noinclude>

第一步,在模板底部添加如上所示的代码。

第二步,页面上现在会出现一个空的文档,点击“创建”链接,打开/doc子页面,并在子页面中编写文档。

<noinclude>[[分类:模板文档]]</noinclude>

第三步,编写文档后,记得在文档底部添加如上所示的代码。

补充说明

本Wiki大部分的模板都按这个模式编写文档,比如{{color}}模板的文档就放在{{color/doc}}下。

实现原理等相关内容可以参考嵌入页面。