# kc-cli 帮助文档
[TOC]
## 当前版本
* v1.0.0
## 安装
> 开始安装之前，请先确定已经安装 node.js . 还有 pandoc(可不装) —— 如果需要文件转换功能的话。
kc-cli 已经发布到 npm ,直接通过 npm 全局安装来安装：
npm install -g kc-cli
在部分系统上，你可能需要加上权限声明，例如在 Ubuntu 上：
sudo npm install -g kc-cli
设计的初衷是一个 CLI 工具，所以 kc-cli 没有 API 可用，不推荐以 node 模块的方式引入到npm 项目中。当然，这不是说绝对不行，以导入文件的方式还是可以拿到 API 的。
## 使用
kc-cli 是辅助大家编辑看云文档的工具，请先从看云把文档仓库克隆到本地。然后进入到文件夹打开终端运行 kc-cli 的相应命令来做操作。
> ps: 一定是看云的文档才行吗？ 不是的，它可以运行在任何文件夹，只是看云文档必须先创建才能编辑，而且创建完成之后它并不是一个空的 Git 仓库。如果你熟悉 Git.你完全在本地弄好一切，最后把看云文档仓库作为远程仓库， push 到看云就可以了。
**小提示**： 如果你的编辑器集成了终端功能，那么你可以省去不少麻烦。推荐：Visual Studio Code。
### 命令及说明
命令|说明
----|----
`kc -h` | 获取帮助信息。
`kc -v` | 获取当前版本。
`kc init`| 初始化看云文档。
`kc theme [cssFilePath] | none`| ——更改文档CSS样式(原有样式会被覆盖)，请提供CSS文件路径。例：<br> kc theme d:/mycss/kanyun.css。<br>1. 如果是` kc theme none `则会删除样式配置文件（文档会使用看云默认样式）。<br>2. 不想要当前样式的时候可以通过`kc theme none`命令清除样式。<br>3. 如果只是微调样式，可以打开website.css文件进行编辑、保存并提交。
`kc summary [dir...]`| 把项目文件夹下的Markdown文件添加到目录文件 `SUMMARY.md` ,输出的文件为:'_summary.md' 。<br>[dir...] 是通配符格式路径，格式和gulp.src([...])一致，只是你不能用[]进行描述，只能像这样：<br>`kc summary 'a/**/*.md' 'b/*.md' '!README.md'`<br> 如果省略则是当前目录下全部的.md文件。
`kc md` | 批量创建 `SUMMARY.md` 中列出的 Markdown 文件。
`kc watch [ignore...]`| 监视任务，当文件发生改变的时候自动执行相应的操作。结果：'kc summary' 和 'kc md'。<br>[ignore...] 排除不监视的文件或文件夹。
`kc docx [name]`| 根据 `SUMMARY.md` 中列出的文件创建 .docx 文件，<br>All in one !,所有文档都在一个.docx文件里。<br>[name] 可以指定输出的文件名，省略则为：out.docx
`kc docx -s` | 根据 `SUMMARY.md` 中列出的文件创建 .docx 文件，一一转换，每个`.md` 有对应的 `.docx` 文件。
`kc html` | 根据 `SUMMARY.md` 中列出的文件创建 .html 文件，是完整的 HTML 文件 。每个`.md` 和 HTML 文件一一对应。
`kc html code` | 根据 `SUMMARY.md` 中列出的文件创建 .html 文件，只是 HTML 片段。每个`.md` 和 HTML 文件一一对应。
#### 命令补充说明
`kc init` 命令，涉及的文件包括：`style/website.css`、`book.json`、`.gitignore`、封面、`README.md`等。 如果这些文件不存在或者不完整，kc-cli 会创建它们，如果这些文件已经存在 kc-cli 会忽略它们不做任何操作。如果你想使用 kc-cli 提供的默认配置，那么你可以删除对应的文件，然后运行 `kc init` 来生成这些文件。这一点得做一个详细的说明：
* `README.md` 对应看云文档的【文档概要】功能； kc-cli 只是创建它，并不会写入多余的内容，如果你已经写好了【文档概要】功能，千万不要删了`README.md`，删了就没了，即便有可能从历史版本中找到，但又何必自找麻烦。
* 封面图片，没有封面图片的话，kc-cli 会有提醒。
* `style/website.css` 看云文档的自定义样式文件。没有的话 kc-cli 会创建并使用看云用户@xiak 提供的配置方案。如果你已经配置过了，那么 kc-cli 会忽略它。如果你不想要自己的方案，想改成 kc-cli 的方案，可以删掉这个文件，然后运行 `kc init` 来得到 kc-cli 提供的CSS配置方案。相应的你也可以对 kc-cli 提供的CSS 方案进行微调、删除，`kc init`命令并不会重复地去更改它。如果你什么样式都不要，那么请把`style/website.css` 文件的代码清空然后保存，不要删，删的话下次运行`kc init`命令的时候还是被创建。
`kc watch` 命令，它是一个监视器任务，当监视的文件发生变化的时候就会执行指定的任务。在这里 kc-cli 监视除`['!node_modules/**', '!./SUMMARY.md','!./_summary.md', '!./README.md']` 以外的所有 `.md` 文件。执行的任务是：`'kc summary' ` 和 `'kc md'`，当运行这个命令之后，终端会被占用，并且已处于运行状态，如果你想停止监视或者结束任务，可以在激活（点击选中）终端之后按 Ctrl+C 中断进程，输入“y” 结束进程。
**kc-cli 依赖终端进行工作，关闭终端会导致进程结束。如果命令没有执行完毕最好不要关闭终端。**
