Home

Awesome

doc-templite explain translate-svg

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

<!-- [中文](./readme.md) | ~~[english](./readme.en.md)~~ -->

explian ✅

<!-- doc-templite START generated --> <!-- repo = 'doc-templite' --> <!-- name = 'chinanf-boy' --> <!-- commit = 'v1.1.1' --> <!-- time = '2018 8.17' -->
版本与日期最新更新更多
commit⏰ 2018 8.17version源码解释
<!-- doc-templite END generated -->

生活

help me live , live need money 💰


<!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> <!-- END doctoc generated TOC please keep comment here to allow auto update -->

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

如这样的格式:

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

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

doc-templite 的 使用 可看

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

准备:借鉴doctoc

钉下注释

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

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

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

以确定目录位置

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

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

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

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

</details>

准备:模版

模版库

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

机缘巧合下, 我看到了 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可以很好的, 起到引领不同模版的效果

输入对象

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

some.md

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

我想有几个点要讲的

那么如何把这些 单行注释 变为 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 注释(单行/多行)

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 // 新文件内容
	}