CentOSでMkDocsを構築する

HTML。Hyper-Text Markup Language。はい、言わずと知れたWebページを作るためのマークアップ言語です。Web担当 神凪です。
最近NCEでは、MarkupよりもMarkdownが主流です。

ちなみにMarkupとMarkdownの違いですが・・・

  • Markup:
    • 文書を構成する文章や文字列に対して、その論理的構成を明示し、どんな文書要素であるかをマーク(指定)すること。
    • 論理的構成を明示するために、一般的にタグと呼ばれる文書要素を指定するための情報を付加する。
  • Markdown:
    • 書きやすくて読みやすいプレーンテキストとして記述すること。
    • 基本的にプレーンテキストのため、記号によって論理的公正を記述する。

と、結構違います。
Markdownだと紙面へのメモでも使えるんですよ。便利です。

さてこのMarkdown文書。そもそもどうやって書くのかはまたの機会に譲ることにします。今回はMarkdownをHTML文書に変換することができるツールのお話。
その名も、MkDocsです。

MkDocsとは?

サックリ言ってしまうと、静的サイト製造ツール、でしょうか? Markdownで書かれたファイルをHTMLに変換してくれます。
自分メモとかであればともかく、ほかの方々にお見せするときはやはり見栄えが良くないとそもそも手に取ってもらえないものなので。

もうちょっとぶっちゃけてしまうと、Wordで書式設定するのが疲れました。HTMLを文書として提出したいのです。
HTMLだって文書ファイルだし、印刷でPDF変換とかできるから大丈夫!

というわけで、さっそく構築していきましょう!

目標

  • MkDocsを使用した静的サイトを構築する。
    • 尚、ほかのシステムと連動した自動構築はまた後日行うこととする

環境

  • CentOS7.3
  • Apache/2.4.6

準備

CentOS初期設定が完了していること
Webサーバ構築が完了していること

手順

Pythonのインストール

MkDocsはPythonに含まれるpipというパッケージ管理ツールによって展開されています。
そのためPythonのインストールが必須です。

とはいえ、上記の準備ができていればPythonはインストールされているはずです。
Pythonのバージョンだけ確認します。

python --version

インストールされていない場合、yumでインストールしてしまいましょう。

yum -y install python

pipのインストール

インストール用スクリプトが配布されていますので、これを使います。

wget https://bootstrap.pypa.io/get-pip.py
python get-pip.py

これでpipインストールは完了です。

MkDocsのインストール

さくっとpipでインストール。

pip install mkdocs

MkDocsプロジェクトを作成する

プロジェクトは文書の集合体を指します。
今回の試みでいえば、静的サイト1つ分をプロジェクト化することになります。

cd /opt
mkdocs new sitedocs
pip install mkdocs-material
cd sitedocs

2行目のsitedocsはプロジェクト名です。ここは任意の名前で構いません。
3行目のmkdocs-materialは、このプロジェクト用にテーマをインストールしています。必要なければ飛ばしていただいても大丈夫ですよ。

MkDocsプロジェクトからHTMLを生成する

サンプル的なファイルは出来上がっていますから、まずはHTML生成をしてみましょう。

mkdocs build

これで/opt/sitedocs/siteに静的HTMLファイル群が作成されました。
出来上がったファイルをアップロードすればそのままサイト公開ができるはずです。

ちなみに、ローカル環境でMkDocsを構築した場合、次のコマンドでプレビューできるようになります。

mkdocs serve

ポート8000を使用した簡易HTTPサーバを構成してくれるようです。ローカル環境でしか使えないため、今回のSandboxでは試せていません。クライアントPC上でMkDocs構築する機会があればお試しくださいませ。

基本的な設定を行う

各プロジェクトはプロジェクトディレクトリ配下にあるmkdocs.ymlというファイルで各種設定を行うことができます。
今回、初期のSandBoxで以下の内容で設定していました。

site_name: NCE Sandbox
site_url: http://sandbox.netcircus.jp/
site_description: NCEの実験場
site_author: '@NCE'
copyright: copyright 2017
google_analytics: null
theme: 'material'
pages:
  - Home: index.md

それぞれオプションは・・・割とそのままの意味なのでここでは割愛。
英語ですがMkDocsのサイトで確認できますので、まずはそちらを見てみましょう。

大事なのはpagesセクション。ここに作成したいHTMLファイルの数だけページタイトル:ファイル名という形で追記していきます。
今はindexだけで十分なのでこれだけです。

おわりに

いかがでしたか? 静的サイト構成ツールはいろいろあるので、NCE的になぜMkDocsを選んだ? と聞かれてもきっと「なんとなく・・・」になるのですが、強いて理由を挙げればMarkdownで書けるから、でしょうかね?
もっと簡単に文書をかけるようになれば、きっと情報整理もたやすくなるはず、と信じています。がんばろっ

Special Thanks!

CloudGarageのDev Assist Program協力のもと、NCEでSandbox、実験場を作成しました。
試せるシステムに限りはありますが、ぜひお試しくださいませ

コメントを残す

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください