Develop
環境構築#
MkDocsの使い方のメモ。
Installation#
MkDocsのインストール；
pip install mkdocs
Warning
MkDocsのインストールはHomeBrewではなくpipで行うこと。
ビルド#
mkdocs.yml があるディレクトリ移動して、サーバーを起動；
mkdocs serve
ブラウザで http://127.0.0.1:8000 にアクセスすれば、 生成されたページを見ることができる。
サーバーを終了するには ctrl + C を入力する。
GitHub Pages を更新するには、以下のコマンドでデプロイする。
mkdocs gh-deploy
必要なパッケージ#
このサイトをビルドするには、下記のパッケージをインストールする必要がある；
pymdown-extensions
mkdocs-material-extensions
fontawesome_markdown
mdx_truly_sane_lists
mkdocs-git-revision-date-localized-plugin
パッケージのインストールは pip install <package> のようにpipコマンドを実行する。
必要なパッケージは requirements.txt に書いておいて、以下のコマンドでまとめてインストールできる；
pip install -r requirements.txt
ローカル環境のメモ#
mkdocsのインストール・管理は、HomeBrew でインストールしたpython 3.9と一緒にインストールされたpip3で行っている。- 管理している pip のパスは
/usr/local/bin/pip3で、~/.zshrcで単にpipとエイリアスを設定している。 - mkdocs を直接 HomeBrew でインストール・管理はしていないので注意。
- 故に、mkdocs のアップデートは
pipコマンドで行う。
pipコマンド#
pip で管理しているものをリスト表示#
pip list
新しいバージョンの有無をチェック#
pip list --outdated
or
pip list -o
pip の更新#
pip install --upgrade pip
or
pip install -U pip
mkdocs の更新#
pip install --upgrade mkdocs
or
pip install -U mkdocs
なお、pip 自体も自動で更新される。
Deploy to GitHub Pages#
GitHub Pagesにデプロイするときのメモ。
GitHub Actionsを用いて、push したときに自動でデプロイするように設定する。
workflowファイル#
Actionsを使うためにworkflowファイルを作成する。
ディレクトリ .github/workflows 内に任意の名前で yml ファイルを作る。
例えば github-pages.yml とかで。内容は以下のものをコピペする；
name: Publish docs via GitHub Pages
on:
push:
branches:
- master
jobs:
build:
name: Deploy docs
runs-on: ubuntu-latest
steps:
- name: Checkout master
uses: actions/checkout@v2
- name: Deploy docs
uses: mhausenblas/mkdocs-deploy-gh-pages@master
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Note
リポジトリの「Settings」>「Actions」の「Workflow permissions」のところで、「Read repository contents permission」にチェックが入っている場合は、Actionsにpush権限がないので、tokenを設定してやらないといけないらしい。 今のところは「Read and write permissions」にチェックを入れているので、特に気にする必要はないっぽい。
ここに書いたworkflowでは、GitHub Actions公式のMkDocsをDeployするActionsを使っている。
デフォルトの設定では、masterブランチにpushがあったときに、gh-deployブランチにビルドしたサイトをpushするようなActionが実行される。
なので、GitHub Pagesで公開するブランチは gh-deploy のルート / を指定する。
また、必要なパッケージは requirements.txt にまとめて書いておくと、自動で読み込まれる。
Info
もちろん細かい設定は変更可能。詳細は公式のマニュアルを参照。