Gitbook を使用してドキュメント センター site_html/css_WEB-ITnose を生成する

Gitbook を使用してドキュメント センター サイトを生成します

1 か月以上経ち、Bugtags は最近独自のドキュメント サイト (docs.bugtags.com) を立ち上げました。そこでは Bugtags の統合が見つかります。 , ほとんどの問題は使用に関するものです。

これまでは、サードパーティが提供するヘルプセンター製品サービスを使用していましたが、その Web サイトのバックエンドでドキュメントのコンテンツを編集し、独自のドキュメント システムを構築しました。少なくとも、私たちの習慣と一致しない点がまだたくさんあることがわかりました。たとえば、製品ドキュメントはリッチ テキスト形式を使用して編集され、データベースに保存されています。ドキュメントを Markdown 形式で作成するのが好きで、データベースの保存は不可能です。ヘルプ センター ページにはテンプレート デザイン機能がいくつかしかありませんが、実際には非常に役に立ちません。カスタマイズのニーズにまったく対応できません。これに基づいて、この問題を解決するための他の解決策を見つけようとします。

私たちのニーズ

まず、どのような種類のドキュメント管理システムが必要かを理解したいと思います。

1. いわゆる「マークダウンなし」のドキュメントを作成します。ドキュメントがありません」; 私たちエンジニアは皆、Markdown を使用してドキュメントを書くことに慣れています。社内で唯一技術者ではない美人の Jingjing でさえ、草稿を促しているときに「どうしてドキュメントが Markdown じゃないんだ！」と言いました。 、彼女はまた、「それはマークダウンでなければなりません。そうでなければ、それを受け入れません。」とも言いました。

2. 生成された Web サイトは純粋に静的であるため、高速になります。当初、私たちは 2 つのオプションを考えていました。1 つは、Markdown ファイルをフロントエンドにダウンロードし、それをフロントエンドで HTML にレンダリングすることでした。もう 1 つは、バックエンドですべての Markdown から HTML を生成し、そのファイルをロードすることでした。フロントエンドでブラウズする場合は HTML を直接使用します。検討した結果、やはり後者のオプションを採用する必要があります。前者の場合、すべてのエンド ユーザーが Markdown のレンダリングにリソースを費やすことは無駄になり、速度は保証されません。後者のアイデアは非常に明確です。最初に Markdown ドキュメントを作成し、ドキュメントの作成後に静的 Web サイトを生成します。これにより、すべてのエンド ユーザーが静的 HTML ページにアクセスできるようになります。

3. git 管理。これについては多くを語る必要はありません。ドキュメントを更新およびアップグレードするには、強力なバージョン管理システムが必要であり、これは git である必要があります。

一連の試みの後、私たちは Gitbook を使用し、それを書き換えて独自のドキュメント センター サイトを生成することにしました。

Gitbook の概要

Gitbook は電子書籍作成プログラムです。この電子書籍の形式は、epub、mobi、pdf、

使用方法も非常に簡単で、基本的には次の 2 つの手順のみです。

gitbook init コマンドを使用します。ファイル SUMMARY.md の内容 ブックのディレクトリ構造を生成するには;
gitbook build を使用して、必要な形式でブックを生成します。
その後、ルート ディレクトリにある book.json ファイルを通じてすべての書籍構成を定義できます。 Gitbook の使用方法の詳細については、Gitbook の簡潔なチュートリアルを参照してください。この Web サイト自体も Gitbook によって生成されています。

Gitbook を採用する理由

Gitbook は私たちのニーズによくマッチしており、以下の点があります:

オープンソース。小規模なスタートアップ企業として、私たちのプロジェクトの多くはオープンソース製品の恩恵を受けています。この製品の開発を促進するためのサードパーティのプラグインが多数あります。
Markdown 形式でドキュメントを作成します。
すべての Markdown ドキュメントは、さまざまなテーマに従ってさまざまなディレクトリ レベルに編成できます。

3. 生成された Web ページは純粋に静的です。 Gitbook はすべての Markdown ドキュメントから静的 HTML ページを生成できます。

4. すべてのコンテンツは Markdown ファイルであるため、バージョン管理と制御に git を使用できます。 🎜> サーバーに Gitbook をインストールした後、ドキュメントの更新が送信されるたびに Web サイトを自動的に生成するように git フック スクリプトをカスタマイズします。

5. Gitbook はニーズに合わせた場所を提供しません

Gitbook 自体のコンセプトは、Markdown ファイルをブックに整理することです。これは、私たちが作成する必要がある Web サイトとは多少異なるため、変更する必要があるものがたくさんあります。

6. 当社の Web サイトを、Gitbook によってデフォルトで生成されるサイト (Gitbook の公式ヘルプ ドキュメント サイトなど) と比較すると、特に次の点が変更されていることがわかります。 🎜>ディレクトリ生成ロジック;

プラグインの使用法;

テンプレートのスタイル。

我们在Gitbook 的模板中添加了页头、页脚。页面目录的样式也不一样：这个可不只是展现形式不一样了。细心翻阅会发现，在我们的文档网站中，有一些文档并没有出现在目录里。比如有很多繁琐的常见问题；如果每一篇都要放到目录里，目录会变得很冗长。这些就得改变 Gitbook 默认的目录菜单的生成逻辑了。

我们是这么做的：在 SUMMARY.md 文件（这个文件中的内容来定义目录结构）中专门定义一个层次，这个层次名称叫做 hide-docs ，类似于这个样子：

- [hide-docs]() - [集成 iOS SDK 看不到悬浮球？](faq/ios/icon-not-found.md) - [用 CocoaPods 集成无法获取最新版的 SDK？](faq/ios/cocoapods-sdk-update.md) - [手动集成 SDK 添加 -ObjC 导致编译出错？](faq/ios/integrate-manual-build-error.md) - [集成 SDK 后，编译产生了很多警告？](faq/ios/integrate-build-warning.md)

这个层级下的所有文档都是不需要出现在目录下的！然而，Gitbook 照样会读取这个层次下的文档，所以我们要在生成目录的逻辑中，稍微改写：判断如果是 hide-docs 这个层级下的文档，就不生成目录。 这个就得改写 Gitbook 程序中的 website.js 文件中的 _writeTemplate 方法，我们的代码是这样：

if( !this.replacedSummary){ this.replacedSummary = {chapters:[]}; if( that.book.summary && that.book.summary.chapters && that.book.summary.chapters.length ){ var chapters = that.book.summary.chapters; for(var i =0; i < chapters.length;i++){ var cur = chapters[i]; if(/hide-docs/.test(cur.title)){ continue; } this.replacedSummary.chapters.push(cur); } } }

然后将该方法返回对象的 summary 属性指定为我们筛选过的 replacedSummary 变量。这样再运行 gitbook build ，就会发现所有的 Markdown 都被生成了 HTML，然而生成的 HTML 页面中的目录不包含这些我们需要隐藏的文档。

插件禁用

Gitbook 默认启用了搜索，字体调整等 5 个插件，但是我们是不需要这些；所以需要通过在 book.json 中指定 plugins 属性为如下：

{ "plugins":["-sharing","-livereload","-search","-fontsettings"] }

用减号表示不启用这些插件（这种配置方法官方帮助文档居然没提）。

搜索

接下来重点的部分就是搜索了，因为 Gitbook 官方的搜索根本不支持中文搜索，所以我们禁用了它，尽管有开源的支持中文的搜索插件，但是搜索结果的展示都是非常不直观；这些都需要从模板以及搜索引擎两方面来改进。

文档搜索我们最后采用的是强大 elasticsearch 来提供全文搜索服务，并且配合修改模板来显示搜索结果。关于 elasticsearch，这是个更复杂的话题了；这里不单说，有兴趣的朋友可以搜索相关教程。

模板

由于 Gitbook 是把 Markdown 组织成一本书的概念；对一本书来说，除了封面就是目录以及目录组织起来的正文。

而我们需要的是一个文档网站，不仅需要文档内容页面，还需要其他的页面， 比如首页，搜索页面， 404 页面，可能还需要其他的页面。这时候我不禁非常怀念 jekyll 这个静态博客生成工具，它会把根目录所有的 HTML 文件找到其对应模板嵌套生成 HTML 页面。

然而 jekyll （以及我另外尝试过的 hexo ）的缺陷是组织 Markdown 文档的方式都比较扁平；是通过在每一个 Markdown 文档的首部定义目录、标签来定义其逻辑层次，而其生成的物理层次则是通过文件名中的日期来定义的。这是个最大缺陷。

目前我是用了比较野蛮的方式来解决这个问题：

• 首页 ：Gitbook 支持多语言，并且如果定义了多语言会有一个模板页面来生成一个首页，来选择语言入口；所以我就把这个本应作为语言选择入口的页面当成我们的首页；恩，就是你现在进去看到的那个页面。
• 404 页面 ：自己写了一个 404，在每次重新生成网站的时候单独把这个文件拷到根目录下；感觉很傻呢……
• 搜索页面 ：每一个内容页都可以是搜索页；因为我是把搜索结果显示在当前页面的内容区域；这样就可以局部刷新来展示页面结果；而不需要单独做一个模板页面了。

成果

最后，我们采用了 Gitbook 符合我们需求的部分，把不适应的上面几点想方设法解决了之后，就形成了我们现在的文档中心站点。

毎日のパブリッシュにも非常に便利で、Markdown ファイルを直接記述し、記述後にサーバーに送信します。ドキュメントが更新されるたびに、サーバー側に git フックが設定され、静的 Web サイトが自動的に再生成され、検索インデックスが再生成されます。バグタグの使用について質問がある場合は、まずここで確認してください。