Skip to content
explian: doc-templite 为多个md文件准备的模版工具
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore
cli.md
doc-templite.md
readme.md

readme.md

doc-templite explain translate-svg

「 为 多个 md 文件准备的 模版工具🔧


explian

版本 与日期 最新更新 更多
commit 2018 8.17 version 源码解释

生活

help me live , live need money 💰


萌生这个工具的念头是, 因为, 要修改多个中文翻译的库中readme.md, 关于 要翻译的原文提供的相关信息

如这样的格式:

翻译的原文 | 与日期 | 最新更新 | 更多
---|---|---|---
 [commit] | ⏰ 2018 7.31 | ![last] | [more]

要修改十几20个文件, 很烦,而且还会有后续的添加, 所以就有了doc-templite

doc-templite 的 使用 可看

好了, 让我们来剖析一下 doc-templite 是如何实现的吧, 我们从准备开始

准备:借鉴doctoc

钉下注释

我一直都有使用doctoc, 来为 md文件 生成目录

而要生成目录, 你需要在文件中添加 doctoc 注释

<!-- START doctoc -->
<!-- END doctoc -->

以确定目录位置

  1. 借鉴这一点, 我定义
doc-templite的注释
    <!-- doc-templite START -->
    <!-- docTempliteId = 'readme' -->

    <!-- doc-templite END -->
  1. 自然doctoc是可以查找目录下的md文件, 继续借鉴这个函数

  2. 每次doctoc生成目录, 就会替换成新的

说明有一个, 更换 doctoc 生成目录的函数 借鉴

准备:模版

模版库

既然是模版工具, 那么就是要有 模版 与 输入值

机缘巧合下, 我看到了 templite 轻量级模板, 只有 150字节

使用简单, 只要两个值: 1. 什么模版 2. 一个输入对象

const templite = require('templite');

templite('Hello, {{name}}!', { name: 'world' });
//=> Hello, world!

什么模版

  1. 模版应该唯一, 且只需要写一次, 相关的输入对象应该由 对应的md文件承担

所以doc-templite需要一个在命令行运行目录存在的

.doc-templite.js

它像这样, 简单输出一个js对象

module.exports = {
  "yobrave":
`name | age
---------|----------
{{ name }} | {{ age }}`,
"readme":
`name | age
---------|----------
{{ name }} | {{ age }}`
}
  1. 我想模版总是不同的, 所以对象中的key可以很好的, 起到引领不同模版的效果
  • "yobrave"
  • "readme"

输入对象

  1. 模版的输入对象, 由相应的md文件定义, 且包裹在 doc-teplite注释

some.md

    <!-- doc-templite START -->
    <!-- docTempliteId = 'readme' -->
    <!-- name = 'yobrave' -->
    <!-- age = 18 -->
    <!-- doc-templite END -->

我想有几个点要讲的

  • docTempliteId 正如我所说的, 不同的id模版由此定义
  • name 而这个
  • age 和这个 自然是 模版的输入对象

那么如何把这些 单行注释 变为 js对象了

  1. 我想我是时候要选择一种 对象解析器, Toml格式

Toml 格式, 就是我选择的

为什么, 不选择自带的 JSON解析, 那么你看看两者的对比

Toml - nice
<!-- name = 'yobrave' -->
JSON - bad
<!-- {"name":"yobrave"} -->

可以看出 JSON 的 字符串转换的 书写, 真的不太行

package.json

我的node包初始化都是使用generator-yobrave生成的

"main": "doc-templite.js",
"bin": "cli.js",

这个工具主要在命令行中使用

cli.js

文字讲讲做了什么

  1. twoLog(cli.flags['D']) 根据命令行的是否Debug, 切换 ora / winston
  1. 确认用户的输入和模版文件.doc-templite.js, 否则 帮助/错误

  2. 根据输入文件/目录找md文件, 汇总组合成数组

  3. 逐个{读取文件内容 运行 doc-templite.js 转换, 拿到结果},拿到结果数组, 期间发生错误, 打印错误退出

  4. 根据--OR命令选项与结果中成功转换的文件, 是否写入覆盖文件

doc-templite.js

文字讲讲做了什么

  1. 拿到单个文件的内容, 看看有没有doc-templite注释,且将 单一注释模版的内容组合 添加到数组

期间可能会出现 doc-templite注释不闭合 的错误

  1. 数组中每个注释模版操作

2.1 逐个注释模版, 找 toml 注释(单行/多行)

  • 其中 找toml的注释 是分 找单行 和 找多行 注释

2.2 切掉 前后注释符号, 交给 toml 解析成js对象

期间出现 toml注释不闭合toml解析 的错误

2.3 从js对象中拿到 模版id (docTempliteId 默认:`yobrave), 并运行模版引擎

期间 会出现id模版找不到 错误

2.4 组合 生成的文档模版, 覆盖上一文件内容(原文/上一模版的覆盖)拿到全新的文件内容, 汇总一下数据, 继续下个模版

注意: 只有文件中所有模版都成功后, 才能说这个文件成功转换

  1. 数组循环结束, 组合数据 返回

供给cli.js

	let result = {
		path: opts.path, // 文件路径
		toml: blocksTomls, // 每个模版中的toml对象 :[{},{}]
		transformed: transformed, // 是否成功转换
		data: data // 新文件内容
	}
You can’t perform that action at this time.