Zenn
Open8

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/