MkDocsを使った簡単なWebサイト作成

2337 ワード
MaterialDesign ホームページ MkDocs webサイト Markdown Markdown テキストリンク

概要

MkDocsというツールを使うことで、簡単にテキストベースのWebサイトの作成ができます。

ちょっとした研究者個人のサイトや、技術系サイトの作成にお勧めです。

MkDocsの特徴

  • Markdown（テキスト+α程度の簡単な言語の記述）で、Webサイトに必要なファイル一式が作れる。HTMLを直にいじらなくてよい。

  • 既存の良さそうなデザインが使える。Material for MkDocksを使うことで、Googleが提唱しているマテリアルデザインを使うことができる。

環境構築

pythonの使える環境があれば使えます。私はWindows上でpythonをインストールし、VSCodeにPython for VSCodeの拡張機能をインストールして、VSCodeのターミナルで以下のコマンドを実行しました。

pip3 install mkdocs
pip3 install mkdocs-material

その後、私の環境では何故かmkdocsのパスが通ってなかったので以下の場所を設定しました。

C:\Users\USERNAME\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.7_qbz5n2kfra8p0\LocalCache\local-packages\Python37\Scripts

Webサイトの作成・編集

新規プロジェクトは以下のコマンドで作れます。

mkdocs new test

そのまま作成されたファイルを開いて編集していきます。

code mkdocs.yml
code .\docs\index.md

マテリアルデザインを使いたい場合は以下の行をymlに追加します。

theme:
  name: 'material'

デザインを少し変えたい場合はここを参照してymlを編集していきます。

mdも自由に編集していきます。
以下のコマンドをターミナルに入力し、ブラウザでhttp://127.0.0.1:8000を開くと、作成しているサイトをファイル更新ごとに確認していくことができます。

mkdocs serve

変更が完了したらHTML, cssなどのファイル一式を生成します。

mkdocs build

プロジェクト配下にsiteというフォルダが生成され、これをWebサーバに置けばWebサイトの作成が完了です。
また、mkdocs gh-deployのコマンドでGitHub Pagesにサイトを構築することもできるようです。