2018-07-03_Mkdocsで静的サイトをつくる

このページでわかること

静的サイトジェネレーターのmkdocsのインストール手順

hexoで全文検索は厳しそうなのでデフォルト対応のmkdocsに乗り換えようと思います。移行手順の備忘録です。

環境

18.04 LTS (Bionic Beaver) ※ubuntu server
Python 2.7.15rc1

移行手順

Pythonのインストール
pipのインストール
mkdocsのインストール
mkdocsでプロジェクトディレクトリの作成
githubにデプロイ

1. Pythonのインストール

インストールされていなければインストールします。

## バージョン確認
$ python --version
Python 2.7.15rc1

## 未導入の場合はインストール
$ sudo apt install python

2. pipのインストール

こちらもインストールされていなければインストールしてください。

1	`$ sudo apt install python-pip`

3. mkdocsのインストール

pipを使いmkdocsをインストールします。 sudoをつけたのは非特権ユーザーでpip installを実施すると~/local/binにインストールされて煩わしい為です。 rootでインストールするとpathの通っている/usr/local/bin/にインストールされて便利です。

## インストール
$ sudo pip install mkdocs

## コマンドの確認
$ which mkdocs
/usr/local/bin/mkdocs

4. mkdocsでプロジェクトディレクトリの作成

mkdocs new ${project_dir_name}で最低限の必要ファイルを作成します。

$ mkdocs new testblog
INFO    -  Creating project directory: testblog
INFO    -  Writing config file: testblog/mkdocs.yml
INFO    -  Writing initial docs: testblog/docs/index.md
$

## 作成された中身の確認
$ cd testblog/ && ls -l
合計 4
drwxrwxr-x 1 iuser iuser 16  7月  3 04:00 docs
-rw-rw-r-- 1 iuser iuser 19  7月  3 04:00 mkdocs.yml

docsディレクトリは*.md形式でファイルを格納します。実際のページに変換されます。
mkdocs.yml はサイトの設定を記載します。

静的ファイルの作成

mkdocs buildコマンドで静的ファイルを作成します。作成されたsiteディレクトリが静的ファイルに変換された一式です。

$ mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /home/hoge/Documents/testblog/site
$

## 作成された中身の確認 (siteディレクトリが追加されている)
$ ls -l
合計 4
drwxrwxr-x 1 iuser iuser 16  7月  3 04:00 docs
-rw-rw-r-- 1 iuser iuser 19  7月  3 04:00 mkdocs.yml
drwxrwxr-x 1 iuser iuser 96  7月  3 04:04 site

内容の確認

mkdocs serveコマンドでローカルでサーバーが立ち上がり記事の内容が確認できます。変更をリアルタイムで追随するので確認しながら修正が簡単にできます。--dev-addrオプションでip指定すると別マシンからもアクセスできます。

1 2	`ipaddr=xxx.xxx.xxx.xxx mkdocs serve --dev-addr=${ipaddr}:8000`

画面としてはこのような表示になります。

5. githubにデプロイ

deployコマンドが用意されているのですがまだ試せていないのでsiteディレクトリ配下を手動でcommit&pushしました。試せたら改めて追記します。