動機

markdownでドキュメントを書く時に、ある程度の量になった場合、章立てを見ながらファイル参照したくなる。
このようなときに記述しやすくて、軽くて、パッケージを入れれば数式や図の記述もできる mdBook というものがあることを知った。
コンテナとして用意して使おうとしたが、オプションの指定でちょっとだけ困ったので、メモとして残しておこうと思う

環境

Ubuntu 18.04

$ cat /etc/lsb-release
DISTRIB_ID=Ubuntu
DISTRIB_RELEASE=18.04
DISTRIB_CODENAME=bionic
DISTRIB_DESCRIPTION="Ubuntu 18.04.2 LTS"
$

Docker-ce 19.03.0

$ sudo docker --version
Docker version 19.03.0-beta4, build e4666ebe81
$
$ dpkg -l | grep docker-ce
ii  docker-ce                             5:19.03.0~1.4.beta4-0~ubuntu-bionic         amd64        Docker: the open-source application container engine
ii  docker-ce-cli                         5:19.03.0~1.4.beta4-0~ubuntu-bionic         amd64        Docker CLI: the open-source application container engine
$

ファイル構成

tree コマンドの結果は、以下のとおり。treeコマンドがなかったら「sudo apt install tree」しておく。

各ファイルの中身

Dockerfile

mdbookを alpine で使う場合、musl用の*.tar.gzが用意されている。素晴らしい。
「自分でコンパイル」を覚悟していたのでこれはうれしい。

# Dockerfile
FROM alpine:3.9

# proxy

# resource
ARG mdbook_dir=/home/mdbook
ARG mdbook_tgz=mdbook-v0.2.1-i686-unknown-linux-musl.tar.gz
ARG mdbook_url=https://github.com/rust-lang-nursery/mdBook/releases/download/v0.2.1/${mdbook_tgz}

# build
RUN apk update && \
    apk --no-cache add curl && \
    apk --no-cache add make sudo tar bash git unzip && \
    rm -rf /var/cache/apk/*

WORKDIR ${mdbook_dir}
RUN curl -L ${mdbook_url} -o ${mdbook_tgz} && \
    tar xf ${mdbook_tgz} && \
    chmod +x ./mdbook && \
    mv ./mdbook /usr/local/bin/mdbook && \
    mdbook init --theme && \
    rm ${mdbook_tgz}

COPY book.toml .
COPY src/ src/

EXPOSE 3000

CMD ["mdbook", "serve", "-d", "/home/mdbook/book"]

Makefile

コンテナ起動時のポイントは、dockerコマンドの--hostnameオプションで指定したホスト名とmdbookコマンドの-nで指定したホスト名をそろえること。dockerコマンドの-pで指定したコンテナ側ポート番号とmdbookコマンドの-pで指定したポート番号が同じこと。

# Makefile
src_dir=/home/user1/work/mdbook/src
name := mdbook-alpine
tag := $(name):1.0
port := 3300

build:
        sudo docker build -f ./Dockerfile . -t $(tag)

run:
        sudo docker run -it --rm -d --name $(name) \
                -p $(port):3000 --hostname="mdbook" \
                -v $(src_dir):/home/mdbook/src $(tag) \
                mdbook serve -d /home/mdbook/book -p 3000 -n mdbook

rm:
        sudo docker rm $(name) -f

ps:
        sudo docker ps -a

img:
        sudo docker images

book.toml

タイトル、著者名や、mathjax, mermaidなど併用するツールの設定を好みに応じここに記載する。

[book]
authors = ["Yuki Niikura"]
multilingual = false
src = "src"
title = "Sample mdbook"

[output.html]
mathjax-support = true

src/SUMMARY.md

サンプルのため、章立ては適当です。


# Summary

- [Chapter 1](./chapter_1.md)
    - [Section_1](./section_1.md)
        - [Subsection_1](./subsection_1.md)
    - [Section_2](./section_2.md)

chapter_1.md 他3ファイル

サンプルのため、中身は適当です

$ cat chapter_1.md
# Chapter 1
resources
- [mdBook document](https://rust-lang-nursery.github.io/mdBook/index.html)
- [mermaid](https://github.com/badboy/mdbook-mermaid)
$
$ cat section_1.md
# Section_1
This is Section 1.
$
$ cat section_2.md
# Section_2
This is section 2.
$
$ cat subsection_1.md
# Subsection_1
This is sub section 1.
$

利用方法

コンテナのビルド、実行

$ make build
$ make run

ブラウザからの参照

コンテナのホストに、実行時に指定した3300番でアクセスし、ドキュメントが見れることを確認する。

Rust製ドキュメントツールmdbookのコンテナ

動機

環境

各ファイルの中身

利用方法