Skip to content

mkdocs wiki

概要

Tips

mkdocsはpython pipで簡単に導入できるMarkDownベースのドキュメント生成ツールです。

導入注記

インストール

Warning

  • mkdocsはjupyter notebook同様にローカルサーバー機能にtornadoを使っています。
  • mkdocsのバージョン1.xx 以降を使うと tornadoのバージョンが5.x以上になり、jupyterが起動しなくなります。
  • また、mkdocsのテーマmaterialの3.xx以降を使うと、mkdocsのバージョン1.xxを要求されます。
  • バージョンに注意して、以下のバージョンを指定して導入しましょう。

関連ライブラリのインストール

pip install mkdocs==0.17.5
pip install mkdocs-material==2.9.4

アンインストールと復旧

Warning

  • 間違ったバージョンを導入してしまった場合は、一度関連するパッケージをuninstallしましょう。
  • 依存しているライブラリも同様にバージョンが強制的に引き上げられている可能性が高いので、 　同様にuninstallすることを推奨します。
  • 復旧完了後 jupyter notebookが起動するかも適切に確認しましょう。

関連ライブラリのアンインストール

pip uninstall mkdocs
pip uninstall tornado
pip uninstall mkdocs-material

関連ライブラリの再インストール

pip install tornado==4.5.1
pip install mkdocs==0.17.5
pip install mkdocs-material==2.9.4

コマンド

新規プロジェクトを作成

mkdocs new [dir-name]

ローカルサーバーを開始

http://127.0.0.1:8000/

mkdocs serve

静的なHtmlを生成

mkdocs build

ヘルプを表示

mkdocs help

設定ファイル mkdocs.ymlの編集

material テーマの適用

Warning

テーマ material の適用には、mkdocs-materialの導入が必要です。

theme:
  name: 'material'

検索日本語対応

  • 以下の設定を追記します。
theme:
  language: 'ja'

extra:
  search:
    language: 'jp'

参考リンク