MkDocs をセットアップする

想定所要時間：5分

👩‍💻 mkdocs のセットアップ

1. mkdocs をインストール

   pip install mkdocs
   

2. テーマのインストール（任意）

   ここでは1番人気のある mkdocs-material をインストールします。

   pip install mkdocs-material
   

   他のテーマはこちらから見ることができます。

3. プロジェクトを作成

   mkdocs new mydocs
   

4. ローカル環境にサーバーを立ち上げる

   mkdocs serve
   

5. ブラウザから http://localhost:8000 にアクセスしてみましょう！

6. 一通り動作確認が済んだら，このプロジェクトを Git リポジトリとして管理しましょう

   git init
   

   Note

   記事やサイトの設定を Git リポジトリで管理していくことになります。

7. .gitignore を作成

   mkdocs では，コンテンツ（markdown ファイル）や設定ファイルをビルドして HTML,CSS,JS のファイルを生成し，これらを site ディレクトリに格納します。

   ただし，これらは Git で管理したいものではないので，無視するために .gitignore ファイルを生成します。

   echo 'site' > .gitignore
   

8. コミットする

   git add .
   git commit -m "init mkdocs project"
   

---

🚀 GitHub にリポジトリを作成して push する

1. GitHub でリポジトリを作成する。

2. 作成したリモートリポジトリに，先ほど作成したローカルリポジトリの内容を push する

   git remote add origin https://github.com/${user_id}/${repos_name}.git
   git branch -M main
   git push -u origin main
   

   ${user_id} と ${repos_name} にはそれぞれ GitHub のユーザー ID と作成したリポジトリ名を指定します。

---

💅 おまけ：スタイルのカスタマイズ

mkdocs-material を使って，ウェブぺージのスタイリングや表現をリッチにできます。

例)

• 数式の利用

  $f(x)=\dfrac{1}{\sqrt{2\pi\sigma}}\exp(-\dfrac{(x-\mu)^ 2}{2\sigma^ 2})$

  ↓

  \(f(x)=\dfrac{1}{\sqrt{2\pi\sigma}}\exp(-\dfrac{(x-\mu)^ 2}{2\sigma^ 2})\)

• ボックスノート

  !!! Note
      これはボックスノートです。
  

  Note

  これはボックスノートです。

詳細は，mkdocs-material のドキュメント を読んでみてください。