コンテンツにスキップ

MkDocsでGitHub Pagesを運用する際のメモ

初期設定⚙️

必要なものをインストールします

  • mkdocsとmkdocs-material（テーマ）、mkdocs-awesome-pages-plugin（記事を降順に並び替えるときに利用）をインストールします
pip install -U pip
pip install -U mkdocs mkdocs-material mkdocs-awesome-pages-plugin

GitHubで公開リポジトリを作ります

  • リポジトリ名がURLのブログタイトルになります

    https://akikuno.github.io/mkdocs-and-ghpages/

  • 公開リポジトリを作るだけでOKです

  • 公開リポジトリをダウンロードします

git clone https://akikuno.github.io/mkdocs-and-ghpages/

mkdocsで記事を作ります

  • ダウンロードしたmkdocs-and-ghpagesディレクトリ下で、以下のコマンドを実行します
mkdocs new .
  • ディレクトリ直下にdocs, mkdocs.ymlの2つが作られます
  • docsディレクトリにindex.mdが作られます

GitHub Pagesにデプロイします

mkdocs gh-deploy
  • ディレクトリ直下にsiteが作られます
    • siteはとくに気にしなくて大丈夫です

テーマを変更します

  • デフォルトでも十分見やすいですが、せっかくなのでテーマを変更してみます

  • ついでに絵文字を表示できるようにします

    • :smile:という表記で絵文字が表示できるようになります😄

  • mkdocs.ymlを以下のように変更します

site_name: MkDocsとGitHub Pages

# テーマを変更します
theme:
  name: 'material'
  palette:
    primary: 'teal'
    accent: 'teal'

# 絵文字を表示します
markdown_extensions:
    - pymdownx.emoji:
        emoji_generator: !!python/name:pymdownx.emoji.to_alt
  • mkdocs.ymlを書き換えたあと、デプロイすれば反映されます
mkdocs gh-deploy

複数記事の投稿📚

  • docs直下に記事をアップしているとサイドバーが見にくくなるので、サイドバーに項目を作ります

  • ここではdocsにblogディレクトリを作ります 

    mkdir -p docs/blog

  • docs/blogディレクトリに記事を2つ作ります 

    echo "# blog1" > docs/blog/blog1.md
echo "# blog2" > docs/blog/blog2.md


mkdocs gh-deploy

記事の表示順を降順にしたい

  • シンプルにURL（マークダウンファイル名）の辞書順（昇順）のようです
    • 以下の構成では1000-01-01が1000-01-02の前に表示されます
echo "# 200" > docs/blog/1000-01-01.md
echo "# 100" > docs/blog/1000-01-02.md

  • 表示順を日付（ファイル名）の降順にしたいときにはMkDocs Awesome Pages Pluginを使います

  • mkdocs.ymlに以下を追記します

plugins:
    - search
    - awesome-pages
  • .pagesに降順設定を書き込むと、.pagesのあるフォルダ内の記事に設定が反映されます
pip install -U mkdocs-awesome-pages-plugin
echo "order: desc" > docs/blog/.pages
  • 👆これでdocs/blog内にあるファイルは逆順（降順）に表示されるようになります

そのほか💡

ライト・ナイトモードの切り替え

  • mkdocs.ymlのtheme下に以下のテキストを追記します
theme:
  palette:
    # Palette toggle for light mode
    - scheme: default
      primary: 'teal'
      accent: 'teal'
      toggle:
        icon: material/weather-night
        name: Switch to dark mode
    # Palette toggle for dark mode
    - scheme: slate
      primary: 'teal'
      accent: 'teal'
      toggle:
        icon: material/weather-sunny
        name: Switch to light mode

シンタックスハイライト

  • pymdownx.highlightとhighlight.min.jsの設定をmkdocs.yamlに追記します
markdown_extensions:
    - pymdownx.highlight

extra_javascript:
    - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/highlight.min.js
    - javascripts/config.js
extra_css:
    - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/styles/default.min.css

yamlの書き方いろいろ

MkDocsによるドキュメント作成

  • 著作権表示やジェネレーターの表記をオフにするなど便利機能がいっぱいあります

注意点⚠️

毎回のGitの認証がめんどう

  • デプロイするときに毎回GitのユーザーIDおよびパスワードを求められるので、以下のコマンドで認証を記憶すると快適です😄
git config --global credential.helper store

mkdocsのインデントが反映されない

  • リストをネストさせる時のインデントがスペース4個です
    • スペース2個では反映されません

ライト・ナイトモードの切り替えを用いるとテーマ色の設定が反映されない

  • ライト・ナイトモードの切り替えを使用するときには、それぞれのsheme内にテーマ色を設定しないと反映されません

  • 以下はOKな例です👌

theme:
  name: 'material'
  palette:
    - scheme: default
      primary: 'teal'
      accent: 'teal'
      toggle:
        icon: material/weather-night
        name: Switch to dark mode
    - scheme: slate
      primary: 'teal'
      accent: 'teal'
      toggle:
        icon: material/weather-sunny
        name: Switch to light mode
  • 以下はダメな例です🙅
theme:
  name: 'material'
  palette:
    primary: 'teal'
    accent: 'teal'
    - scheme: default
      toggle:
        icon: material/weather-night
        name: Switch to dark mode
    - scheme: slate
      toggle:
        icon: material/weather-sunny
        name: Switch to light mode
  • ダメな例でもエラーなくデプロイされるので、原因がわかるまで時間がかかりました…

参考資料 🙇

最終更新日: February 23, 2023