MkDocs¶
Python製の静的サイトジェネレータ。
ページ構成を多段にできないので、あまりスケールできないと思われる。
※mkdocs-materialだと少なくとも2階層にはできる。
Getting Started¶
参考:
Installation¶
いくつか選択肢がある
- パッケージマネージャー
pip install mkdocs
後述のmkdocs-materialを使うなら、そちらのDockerイメージを使う手も有る。MkDocsも含まれているので。
参考:
Quickstart¶
https://www.mkdocs.org/#getting-started
Usage¶
ページの追加¶
https://www.mkdocs.org/#adding-pages
- docs/ 以下にMarkdownファイルを追加
- config file (mkdocs.yml) で設定
設定例:
GitHub Pagesへのデプロイ¶
公式マニュアルがあるが、GitHub ActionなどCIを利用した方が楽だろう。
GitHub Action¶
下の参考記事に上げた@peaceiris先生の記事に詳しいやり方が載っているので、一読すると良い。
2020-07-17、binqry.github.ioでは次のように設定した。
name: github pages
on:
push:
branches:
- source
jobs:
deploy:
runs-on: ubuntu-18.04
steps:
- uses: actions/checkout@v2
- name: Setup Python
uses: actions/setup-python@v2
with:
python-version: '3.x'
architecture: 'x64'
- name: Cache dependencies
uses: actions/cache@v2
with:
path: ~/.cache/pip
key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
restore-keys: |
${{ runner.os }}-pip-
- name: Install dependencies
run: |
python3 -m pip install --upgrade pip
python3 -m pip install -r ./requirements.txt
- run: mkdocs build
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./site
publish_branch: master
参考:
公式マニュアル¶
https://www.mkdocs.org/user-guide/deploying-your-docs/
下のコマンドがある。
User / Organizationリポジトリの場合、単にこのコマンドを実行するだけでは上手く行かない。
Themes¶
一覧: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
Pickup:
- ReadTheDocs ... 組み込み。色んなところで使われている。そつない見た目で、使いやすい
- ReadTheDocs Dropdown ... ReadTheDocsの拡張。ドロップダウンメニュー対応
- mkdocs-material ... 非常に人気の高いテーマ
mkdocs-material¶
参考:
Installation¶
いくつか選択肢がある:
pip install mkdocs-materialdocker pull squidfunk/mkdocs-material- リポジトリをgit cloneして使う
参考:
Features¶
- ページタブ(後述)
- Extensions
- Markdown拡張
- CodeHilite ... シンタックスハイライト
- Admonition ... warn, infoなどのブロック要素
- Footnotes
- PyMdown
- superfences
- Markdown拡張
- Plugins
Configuration¶
タブ機能を有効にするとページをグループ化できる。