Open14

MkDocsの使い方

Python 3
MkDocs
shotakahashotakaha

インストール

$ pip3 install mkdocs

$ pipx install mkdocs

$ uv tool install mkdocs

$ brew install mkdocs
shotakahashotakaha

新規作成

$ mkdocs new PROJECT_NAME
INFO    -  Creating project directory: PROJECT_NAME
INFO    -  Writing config file: PROJECT_NAME/mkdocs.yml
INFO    -  Writing initial docs: PROJECT_NAME/docs/index.md

$ ls PROJECT_NAME
mkdocs.yml
docs/
  • mkdocs new プロジェクト名 で新規作成
    • 「プロジェクト名」のディレクトリが作成される
    • その中にmkdocs.ymlとdocs/ディレクトリが作成される
      • mkdocs.yml: 設定ファイル
      • docs: コンテンツを格納するディレクトリ
  • mkdocs new . すると既存のプロジェクトに追加できる
    • カレントディレクトリにmkdocs.ymlとdocs/ディレクトリが作成される
  • 「プロジェクト名」を指定しないとエラーになる
shotakahashotakaha

プレビュー

$ cd プロジェクト名
$ mkdocs serve --open
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.04 seconds
INFO    -  [11:33:53] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [11:33:53] Serving on http://127.0.0.1:8000/
  • mkdocs.ymlがあるディレクトリに移動する
  • mkdocs serveでローカルサーバーが起動しライブプレビューできる
  • --openオプションでブラウザが起動する
shotakahashotakaha

ビルド

$ mkdocs build
mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory:PROJECT_NAME/site
INFO    -  Documentation built in 0.03 seconds

$ ls
mkdocs.yml
docs/
site/
  • mkdocs buildで静的ファイルを生成する
  • 静的ファイルはsiteディレクトリの中に作成される
    • siteディレクトリは.gitignoreしたほうがよい
shotakahashotakaha

設定ファイル（mkdocs.yml）

# Project information
site_name: サイト名
site_url: ウェブサイトのカノニカルなURL
repo_url: リポジトリのURL
repo_name: # "GitHub" / "Bitbucket" / "GitLab"
edit_uri:
edit_uri_template:
site_description:
site_author:
copyright:
remote_branch: "gh-pages"
remote_name: "origin"

# Documentation Layout

nav:
  - Home: index.md
  - About: about.md

exclude_docs:
draft_docs:
not_in_nav:
validation:

# Build Directories
theme:
  name: readthedocs  # or mkdocs
  locale: ja

docs_dir: docs
site_dir: site

extra_css: []
extra_javascript: []
extra_templates: []
extra: {}

# Preview Controls
watch:
use_directory_urls: true  # pretty_url / ugly_url に相当
strict: false
dev_addr: "127.0.0.1:8000"

# Formatting Options
markdown_extensions:
  - smarty
  - toc:
      permalink: true
      separator: "-"
  - sane_lists
hooks:
plugins: ["search"]
  • mkdocs.ymlにサイト設定を記述する
  • themeはmkdocs or readthedocsから選ぶ
    • （追加・拡張する方法はあとで調べる）

https://www.mkdocs.org/user-guide/configuration/

shotakahashotakaha

MkDocsカタログ

https://github.com/mkdocs/catalog

  • mkdocs関係のパッケージのリスト用リポジトリ
  • まず、この中から目的にあったパッケージを探してみるとよさそう
shotakahashotakaha
$ pip3 install "mkdocs-material[imaging]"

$ uv add "mkdocs-material[imaging]"
shotakahashotakaha

Material for MkDocs の設定

https://squidfunk.github.io/mkdocs-material/creating-your-site/#minimal-configuration

  • まずはこのminimal configurationを参考にthemeをMaterial for MkDocsに設定する
  • その後、その下にあるAdvanced configurationから必要な設定を追加する
shotakahashotakaha

Markdown Extensions

https://squidfunk.github.io/mkdocs-material/setup/extensions/

  • デフォルトでは、コードブロックがシンタックス・ハイライトされない
  • なのでMadkdown Extensions は設定したほうがよい
  • Python Markdown とPython Markdown Extensionsの2種類のセクション設定がある
  • まずminimal configuration を設定してコードブロックがきちんと表示されるかを確認し、反映されていればrecommanded configurationを全部盛りすればOK
  • あとは、ドキュメントにある説明と設定方法を確認し、取捨選択する
shotakahashotakaha

i18n

https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/

  • メインの言語を設定する
theme:
  language: ja
  • 多言語を設定する
theme:
  language: ja

extra:
  alternate:
    - name: English
      link: /en/  # <- 絶対パスにする
      lang: en
    - name: Deutsch
       link: /de/
       lang: de

ディレクトリの構造

  • 言語ごとにサブディレクトリを作成する
  • その中に翻訳コンテンツを作成する
mkdocs.yaml
docs/
  |-- index.md
  |-- en/index.md
  |-- de/index.md
shotakahashotakaha

ブログ設定

https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/

  • ビルトインのblogプラグインを利用する（追加パッケージは不要）
    • ただし、RSSを追加する場合は追加パッケージが必要

ディレクトリ構造

|-- mkdocs.yaml
|-- docs/
      |-- index.md
      |-- about/
      |-- blog/
            |-- index.md
            |-- posts/
                  |-- この中に記事を配置する
                  |-- 2024/
                        |-- サブディレクトリ/index.md
  • blogプラグインを有効にしてビルド（or プレビュー）すると、docs/blog/index.mdが作成される
  • その中にdocs/blog/posts/の空ディレクトリも作成される。ユーザーはこの中に記事ファイルを作成する必要がある
    • ドキュメントをきちんと読まずに、blog/の下に記事ファイルを作成して、うまくいかないなと悩みました