mkdocs-materialとGitHub PagesでMkDocsを作成する

Install

pip install mkdocs-material

ｍｋdocs作成

1. MKDocsの初期化

   mkdocs new .
   

   結果

   tree
   .
   ├── docs
   │   └── index.md
   └── mkdocs.yml
   
   1 directory, 2 files
   

2. テーマをmkdocs.ymlで指定

   mkdocs.yml

   site_name: My Docs
   theme:
     name: material
   

3. ローカルで起動

   mkdocs serve
   

   

4. ビルド

   mkdocs build
   

   site/ 以下に生成される

5. GitHub Pagesで公開する (gh-deploy branchにPush)

   1. GitHub Pagesの設定: 以下のようにgh-pagesブランチを指定する

      

   2. GitHub Actions作成 (main branchにPushされたらDocsをビルドしてDeployする)

      .github/workflows/publish.yml

      name: publish
      
      on:
        push:
          branches:
            - main
      jobs:
        deploy:
          runs-on: ubuntu-latest
          steps:
            - uses: actions/checkout@v2
            - uses: actions/setup-python@v2
              with:
                python-version: 3.9
            - run: pip install mkdocs-material
            - run: mkdocs gh-deploy --force
      

   3. GitHub Actionsを含めて、RepoへPush

   4. https://nakamasato.github.io/mkdocs-material-sample/公開された! (自分の場合は、カスタムDomainを使っているので nakamasato.comとなった)

6. テーマ変更

   色などを変更できる

   site_name: mkdocs sample
   theme:
     name: material
     palette:
       primary: cyan
   

   

Reference

• https://squidfunk.github.io/mkdocs-material/creating-your-site
• https://github.com/nakamasato/mkdocs-material-sample