如何制作dash的docset [以Elastic stack各文档为例]

dash，是macOS上一个极其有用的软件，通过dash，我们可以将各种技术文档离线下载到本地，然后进行快速的检索。并且，dash以IDE插件的形式，提供IDE等工具上的快速检索，你可以在IDE上通过快捷键，将你不熟悉的函数，方法，注解等快速定位到dash当中

Elastic stack提供了大量的工具，并且版本发布频繁，要很好的使用它们，常常需要查看文档，怎奈 官网 的访问速度在国内并不尽如人意，并且很多时候，并不一定有访问外网的网络环境，因此，我们需要离线的文档库，可以让我们快速的查看。下面，我们就来看看如何搭建我们自己的本地文档库。

dash

首先，你需要拥有一个本地文档库工具，我这里推荐的是dash。并且，dash的官方仓库里面已经提供了elasticsearch的文档。

因此，我们只需要自己制作kibana，logstash，filebeat等工具的docset

从git上下载源文档

要制作离线文档，首先得有文档的源文件。
以logstash为例，首先访问github：
https://github.com/elastic/logstash

elastic下的每一个项目都有docs文件夹

执行以下命令，只把docs目录clone到本地

cd mydocs
mkdir logstash_master
git init
git remote add -f  origin https://github.com/elastic/logstash.git
git config core.sparseCheckout true
echo 'docs' >> .git/info/sparse-checkout  
git pull origin master

如果觉得以上操作还觉得麻烦，可以直接进入这个网站：DownGit

转化为HTML文档

可以看到文档都是asciidoc格式的：

我这里还是用官方建议的方法进行转换：

• 先下载 转换工具
• ~/path/to/docs/repo/build_docs --doc path/to/index.asciidoc --toc --out output/dir/

这里一定要记得加 --toc ，这里会添加生成一个toc.html，包含所有的目录信息。

另外，这个工具会首先清空output目录，不要把output目录指定错了，否则损失不可挽回 。

logstash的例子，执行以下命令：

./build_docs --doc /Users/caishichao/mydocs/logstash_docs/docs/index.asciidoc --toc --out ../logstash

会生成如下HTML文档：

使用dashing

首先下载：

brew install dashing

然后进入目录，并创建dashing配置文件：

$ cd logstash
$ dashing create

以上命令会在目录里面生成一个dashing.json文件，编辑之：

{
    "name": "Logstash",
    "package": "logstash",
    "index": "index.html",
    "selectors": {
        "li.chapter a": "Guide",
        "li.part a": "Guide"
    },
    "ignore": [
        "ABOUT"
    ],
    "icon32x32": "",
    "allowJS": false,
    "ExternalURL": ""
}

具体可参考：https://github.com/technosophos/dashing#readme ； https://kapeli.com/docsets ；

然后执行:

$ dashing build

会生成logstash.docset

本地加载docset

本地加载后即可打开