给代码块加上可填写的示例参数:Chaos主题的code_vars和其他一些近期更新
我平时会写不少技术文档。其中的示范代码,特别是涉及命令行操作的部分,往往包含一些需要临时填写并在后文重复使用的参数,读者不能直接照搬例子去运行,而是需要先做一些修改才能使用。
前几天在写生成SSHFP和TLSA记录这篇作弊条的时候,我顺手给本站使用的Chaos主题加上了一个可交互的示例参数功能,并把之前合并BIND 9子域等几篇旧文也一并改了过来。
从减少重复手工操作、避免忙中出错的角度来说,许多时候(尤其是对于「作弊条」这类题材的内容),比较理想的文档形式应该是一个可以填写、填完就能直接复制的模板。这是因为在这些操作里,变量(或者说需要读者填写的内容)通常是主机名、IP地址,或是本地某条命令的输出结果(例如公钥的hash值),而其余参数则应与原文保持严格一致,且同一组参数往往会贯穿全文。
例如在TLSA和SSHFP那篇里,域名example.net、邮件服务器mx1、SSH主机beastie,以及前一步刚用OpenSSL算出来的公钥SHA-256和SHA-512散列值,会在后面的命令行和BIND区域文件模板里反复出现。假如完全靠手工在各个代码块之间来回查找替换,不仅繁琐,而且漏改或是贴错一段,还很容易导致一些其他问题。
在一些文档系统的DSL中,有一种用<var>标签标记的可编辑占位符:在渲染出来的页面上填入新值之后,整篇文档里的示例命令就会跟着一起变,点复制按钮拿到的也是替换好的命令。我认为这种交互非常适合类似作弊条这样的内容,于是用Antigravity给Chaos主题也做了一套类似的实现。这里记录一下它在实际文章中的写法,以及在迭代过程中考虑的一些细节。
