mdbook 与 Nginx 下的内容发布 Web 站点管理

mdbook 是 Rust 实现的一个类似于 gitbook 的文档服务器，通过使用 MarkDown 编写文档，mdbook 可将其构建为 HTML、PDF 目标，并可运行 HTTP 服务器，在线提供文档。咱们使用 Nginx 做 mdbook 的反向代理，带来高并发、SSL/TLS 等额外功能。

以下是在建立此种文档服务器时，用到的一些配置与脚本。

include 自己的一些行

include 指令可以重用 Markdown 文档中的一些行。在 linux.md 中写下双花括号括起来的 #include ./linux.md:119:191 便可以引用 linux.md 本身的 119 到 191 行。

服务器管理脚本

文件：srv_incl.sh

{{#include ../projects/srv_incl.sh}}

文件：srv_mgt.sh

{{#include ../projects/srv_mgt.sh}}

Nginx 配置示例

文件：/etc/nginx/nginx.conf

{{#include ../projects/nginx.conf}}

文件：/etc/nginx/conf.d/ccna60d.conf

{{#include ../projects/ccna60d.conf}}

一个域名下多本书的配置

此需要是通过 Nginx 反向代理中，URL 重写的设置实现的。相较于一个域名一本书的 Nginx 设置，略有差别。

{{#include ../projects/mdbook-nginx.conf}}

其中，差别在于这里：

        location /xiaohu/zh/ {
                proxy_pass http://xiaohu-zh/;
        }

proxy_pass http://xiaohu-zh/ 最后多了一个斜杠。

参考：Nginx reverse proxy + URL rewrite

单个域名下同步单个仓库，提供多本书的操作流程

1. 在代码仓库根目录下建立一本新书对应的目录。此目录下应有 src、theme 目录及 book.toml 文件等必要组成部分，所有内容的 MarkDown 文件都在 src 目录下；

2. 修改 src_inc.sh 文件，添加上面新书的目录，以及新书的端口；

3. 修改 Nginx 的配置文件 /etc/nginx/config.d/docs.conf，添加新书的 upstream 设置及反向代理路径；

4. 运行 srv_mgt.sh start demo-book & 及 systemctl restart nginx 启动新书，并重启 Nginx。

NS_ERROR_NET_PARTIAL_TRANSFER 问题

由于 mdbook 中用于代码高亮的 hljs 过大（1M+），加载文件时会出现此问题。需要修改 Nginx 配置参数，将以下内容加入 /etc/nginx/nginx.conf：

        gzip  on;
        gzip_min_length 1k;
        gzip_buffers 4 16k;
        gzip_http_version 1.0;
        gzip_comp_level 2;
        gzip_types text/plain application/x-javascript text/css application/xml;
        gzip_vary on;

        proxy_http_version 1.1;
        proxy_buffer_size 128k;
        proxy_buffers 4 256k;
        proxy_busy_buffers_size 256k;

参考：nginx 解决 NS_ERROR_NET_PARTIAL_TRANSFER

对默认不支持的编程语言，增加语法高亮

以 Groovy 为例。

首先下载新版本的 hljs （highlight.zip）。将其中的 highlight.min.js 拷贝到书本的 theme/highlight.js ，mdbook 将自动使用新版本的这个主程序。然后从 highlight.zip 中选择要增加的语言模式文件，比如 languages/groovy.min.js，将其拷贝到 theme/groovy.min.js。

随后修改 book.toml：

...

[output.html]
additional-css = ["theme/pagetoc.css"]
additional-js  = ["theme/pagetoc.js", "theme/groovy.min.js"]

...

修改 theme/index.hbs：

      <script src="{{ path_to_root }}clipboard.min.js"></script>
      <script src="{{ path_to_root }}highlight.js"></script>
      <script src="{{ path_to_root }}book.js"></script>
      <script src="{{ path_to_root }}theme/groovy.min.js"></script>
    <!--Enable new hljs language mode.-->
      <script>hljs.initHighlightingOnLoad();</script>

然后提交到代码仓库，在服务器上重启该书本即可。

（End）