技(jì )术资料

大家好，“Geeki说”时间又(yòu)到了！掐指一算，每一个和集群打交道的工(gōng)程师们電(diàn)脑里最重要的文(wén)件资料排行前三名(míng)一定有(yǒu)“集群文(wén)档”。没错，就是大家辛辛苦苦忙了大半个月甚至忙了更久的劳动成果！这一期，就让我们来分(fēn)享一下面对数量庞大、需要不断更新(xīn)的集群文(wén)档，奥工(gōng)小(xiǎo)分(fēn)队有(yǒu)什么管理(lǐ)的好办(bàn)法吧！

01/静态页(yè)面需求

一个高性能(néng)集群从规划实施到部署验收完成，需要输出大量各种各样的文(wén)档，其中(zhōng)包括部署实施前的实施规划、实施计划；部署实施中(zhōng)的实施报告、测试报告；部署实施结束后的验收文(wén)档、使用(yòng)手册等等。

奥工(gōng)小(xiǎo)分(fēn)队队员的電(diàn)脑里可(kě)以说塞满了各式文(wén)档，我们在实施部署过程中(zhōng)会将每个客户的文(wén)件资料细心整理(lǐ)，并在验收后把文(wén)档打包交给客户。

大部分(fēn)文(wén)档在验收完成后内容是固定不会变动的，但是对于用(yòng)户集群的使用(yòng)手册等文(wén)档，难免会随着集群的使用(yòng)变化而出现一些变动（比如ip的修改、功能(néng)的调整等）。针对这种情况，一款在線(xiàn)可(kě)以解决用(yòng)户手册查找问题使用(yòng)手册就是非常棒的“小(xiǎo)帮手”了!

那么该选择一款什么样的在線(xiàn)文(wén)档输出方式呢(ne)?奥工(gōng)小(xiǎo)分(fēn)队千挑万选“相中(zhōng)”的一款静态网页(yè)方案就可(kě)以满足上述需要——MkDocs，它的使用(yòng)改变了以往通过“邮件”“微信群”等滞后的文(wén)档传输方式，实现了在線(xiàn)输出和实时修改，给予了用(yòng)户更好的使用(yòng)體(tǐ)验。

（MkDocs页(yè)面展示）

02/MkDocs為(wèi)何物(wù)？

MkDocs 是一个简单、快捷、几乎完美的静态站点生成器，是奥工(gōng)小(xiǎo)分(fēn)用(yòng)来创建说明文(wén)档的有(yǒu)力工(gōng)具(jù)，目前有(yǒu)五大优点和大家展示一下：

①任意托管：构建纯静态的HTML网站，可(kě)以托管到 GitHub pages、 Amazon S3 等任意地方；

②大量主题：除了有(yǒu)内置主题备选外，还可(kě)以定制构建自己的主题；

③及时预览：内置开发服務(wù)器允许在撰写时即时预览文(wén)档并在保存更改时自动加载更新(xīn)；

④易于配置：通过一些简单的自定义和插件安(ān)装(zhuāng)，项目文(wén)档可(kě)以变成你想要的样子；

⑤门槛较低：只要熟悉Markdown页(yè)面规则即可(kě)，不需要任何前后端代码能(néng)力。

说了这么多(duō)优点，来看点实际的，MkDoce中(zhōng)文(wén)文(wén)档页(yè)面展示▼▼▼

PS：MkDocs 官方中(zhōng)文(wén)文(wén)档就是使用(yòng)的自家的内置主题之一——mkdocs静态页(yè)面方式。

03/页(yè)面使用(yòng)规则

说到这，大家一定跃跃欲试，很(hěn)关心页(yè)面使用(yòng)规则吧。对于MkDocs的页(yè)面规则，使用(yòng)者可(kě)能(néng)不仅需要参见下MkDocs的官方文(wén)档，还需要参考下 Markdown页(yè)面规则定义方式。

Markdown是什么？和MkDocs有(yǒu)什么关系呢(ne)？简单来说Markdown是一种轻量级标记语言，它允许人们使用(yòng)易读易写的纯文(wén)本格式编写文(wén)档。MkDocs页(yè)面正完全依赖于Markdown页(yè)面输出模式以便形成易于阅读、浏览的方式，但是Markdown的文(wén)档书写方式的确也令很(hěn)多(duō)初學(xué)者感到些许不适应……没关系，奥工(gōng)小(xiǎo)分(fēn)队经验之谈告诉你“只要配合git仓库的方式”就可(kě)以轻松有(yǒu)效地解决这类问题。现有(yǒu)的git托管网站对Markdown规则做了很(hěn)好的适配，可(kě)以在网页(yè)上直接修改，实现边改边看；或者使用(yòng)现有(yǒu)的cs工(gōng)具(jù)来书写Markdown页(yè)面然后同步git仓库或者上传服務(wù)器本地的方式去实现。奥工(gōng)小(xiǎo)分(fēn)队比较熟悉Markdown规则，习惯使用(yòng)比较“土”的一种方式——直接服務(wù)器本地文(wén)本修改，简单又(yòu)快捷！

04/MkDocs的安(ān)装(zhuāng)

MkDocs的安(ān)装(zhuāng)比较简单，就四步：

①首先需要一个python环境：miniconda或者anaconda

②配置好环境后使用(yòng)pip 安(ān)装(zhuāng) mkdocs：

③开始生成第一个在線(xiàn)文(wén)档：

④启动服務(wù)：mkdocs serve

启动后自动会得到一个地址，访问该地址即可(kě)打开页(yè)面。

05/编辑页(yè)面

安(ān)装(zhuāng)完成后，开始添加内容。针对安(ān)装(zhuāng)生成的project项目中(zhōng)有(yǒu)关mkdocs.yml的定义，该文(wén)件定义的目录结构可(kě)以在docs文(wén)件夹中(zhōng)定义的文(wén)件/文(wén)件夹来设置文(wén)档章节，新(xīn)建各章节的md文(wén)件就可(kě)以将各章节的内容區(qū)分(fēn)开来编辑。

话不多(duō)说，直接给出奥工(gōng)小(xiǎo)分(fēn)队维护的网页(yè)目录结构：

相应的页(yè)面内容修改完成后，即可(kě)直接在浏览器中(zhōng)查看到所共享的内容，如果后期内容出现修改，页(yè)面可(kě)以实时更新(xīn)，客户可(kě)以第一时间得到最新(xīn)内容。

MkDocs凭借低门槛、实时更新(xīn)的优势得到了奥工(gōng)小(xiǎo)分(fēn)队的青睐，但MkDocs并不是集群文(wén)档管理(lǐ)的唯一选择，还有(yǒu)其他(tā)的静态网站生成器各有(yǒu)优劣，这里不多(duō)加赘述啦！本期到此為(wèi)止，下期会分(fēn)享些什么呢(ne)？请期待吧！