コンテンツにスキップ

MkDocs Hub

adin

  • Admonition
  • 文書内にメモ、ヒント、警告などが目立つようなスタイルで表示する
  • material テーマをインストールすると一緒にインストールされる
  • footnotes
  • 注釈をつける
  • つけたい言葉の後ろに[^1]
  • 説明は[^1]: 文書を記述するための軽量マークアップ言語のひとつ

memo

  1. CT（コンテナ）の状態確認 まず、コンテナが適切に動作しているか確認しましょう。
root@hrnpm:~# pct exec 104 -- hostnamectl
 Static hostname: mkdocs
       Icon name: computer-container
         Chassis: container ☐
      Machine ID: b289032f916b4d319dba2e3ddc91b12b
         Boot ID: 850fe843b9b749408d93107d82bded12
  Virtualization: lxc
Operating System: Debian GNU/Linux 12 (bookworm)  
          Kernel: Linux 6.8.12-4-pve
    Architecture: x86-64

root@hrnpm:~# pct exec 104 -- ip a
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet 127.0.0.1/8 scope host lo
       valid_lft forever preferred_lft forever
    inet6 ::1/128 scope host noprefixroute 
       valid_lft forever preferred_lft forever
2: eth0@if93: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
    link/ether bc:24:11:09:9e:7f brd ff:ff:ff:ff:ff:ff link-netnsid 0
    inet 192.168.11.204/24 brd 192.168.11.255 scope global eth0
       valid_lft forever preferred_lft forever
    inet6 2001:f76:4840:2600:be24:11ff:fe09:9e7f/64 scope global dynamic mngtmpaddr 
       valid_lft 7181sec preferred_lft 3581sec
    inet6 fe80::be24:11ff:fe09:9e7f/64 scope link 
       valid_lft forever preferred_lft forever
  1. Debian 12 CTに必要なパッケージをインストール コンテナにログインして、必要なパッケージをインストールします。 apt update && apt upgrade -y Python 3 と pip が入っていることを確認。
python3 --version
pip3 --version
  1. Pythonのアップグレードとpipの導入
apt update
apt install -y python3-venv python3-pip

root@mkdocs:~# python3 --version
Python 3.11.2

root@mkdocs:~# pip3 --version
pip 23.0.1 from /usr/lib/python3/dist-packages/pip (python 3.11)
root@mkdocs:~#
  1. MkDocsの推奨バージョンを確認・インストール MkDocsの公式サイトでは、最新の安定バージョンを pip で管理することが推奨されています。

エラー発生

root@mkdocs:~# pip3 install --upgrade pip
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.

    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.

    See /usr/share/doc/python3.11/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

このエラーは、Debian 12 が PEP 668 (Externally Managed Python Environments) を採用しており、pip で直接システムのPythonに変更を加えないようにしているために発生しています。

Debian 12 のデフォルト環境（Python 3.11.2 + pip 23.0.1）をそのまま使って MkDocs を構成することは 可能 です。

しかし、DebianのシステムPython環境を直接変更すると、将来的なパッケージの管理が難しくなることがあります。 そのため、長期的には 仮想環境 (venv) を使うのが推奨 されますが、特に問題がなければ そのままpipでMkDocsをインストールしても大丈夫 です。

  1. そのままpipを使ってMkDocsをインストールする手順
pip3 install mkdocs mkdocs-material

エラー発生。 Debian 12 では PEP 668 によってシステムPython環境が保護されており、pip でシステム全体に直接パッケージをインストールできないようになっています。とのこと 仮想環境使えって。

  1. pipxを使う pipx を使うと、仮想環境を自動的に作ってくれるので、管理が楽になります。
apt install -y pipx
pipx install mkdocs

⚠️  Note: mkdocs was already on your PATH at /usr/bin/mkdocs
  installed package mkdocs 1.6.1, installed using Python 3.11.2
  These apps are now globally available
    - mkdocs
⚠️  Note: '/root/.local/bin' is not on your PATH environment variable. These apps
    will not be globally accessible until your PATH is updated. Run `pipx
    ensurepath` to automatically add it, or manually modify your PATH in your
    shell's config file (i.e. ~/.bashrc).
done! ✨ 🌟 ✨

動作確認:

pipx run mkdocs --version

⚠️  mkdocs is already on your PATH and installed at /usr/bin/mkdocs. Downloading
    and running anyway.
mkdocs, version 1.6.1 from /root/.local/pipx/.cache/13aefee2ac35dd9/lib/python3.11/site-packages/mkdocs (Python 3.11)

MkDocsを使う

pipx run mkdocs serve

エラー発生

⚠️  mkdocs is already on your PATH and installed at /usr/bin/mkdocs. Downloading
    and running anyway.
Error: Config file 'mkdocs.yml' does not exist.

エラーの原因は mkdocs serve を実行するディレクトリに mkdocs.yml が存在しないためです。 これは MkDocsのプロジェクトがまだ作成されていないため に発生しています。

  1. mkdocs.yml を含むプロジェクトを作成
mkdir ~/my_mkdocs_project
cd ~/my_mkdocs_project
pipx run mkdocs new .

サーバの起動

pipx run mkdocs serve

ブラウザからアクセスできない（ページに到達できない）

⚠️  mkdocs is already on your PATH and installed at /usr/bin/mkdocs. Downloading
    and running anyway.
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.05 seconds
INFO    -  [08:05:46] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [08:05:46] Serving on http://127.0.0.1:8000/
^CINFO    -  Shutting down...
root@mkdocs:~/my_mkdocs_project# pipx run mkdocs serve
⚠️  mkdocs is already on your PATH and installed at /usr/bin/mkdocs. Downloading
    and running anyway.
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.05 seconds
INFO    -  [08:05:54] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [08:05:54] Serving on http://127.0.0.1:8000/

mkdocs serve が 127.0.0.1:8000 でサーバーを起動しているため、コンテナの外からアクセスできない 状況になっています。 mkdocs serve を --dev-addr 0.0.0.0:8000 オプション付きで実行してください。 127.0.0.1 はコンテナ内部のローカルアドレスなので、ホストPCや他の端末からアクセスできない。 0.0.0.0 に変更すると、コンテナの外部（Proxmoxのホストや他のPC）からもアクセス可能 になる。

pipx run mkdocs serve --dev-addr 0.0.0.0:8000

アクセス確認

http://192.168.11.204:8000/

無事アクセスすることができた。

  1. nohup を使いターミナルセッションを切っても動作するようにする nohup は、ターミナルを閉じてもプロセスが終了しないようにするコマンドです。
nohup pipx run mkdocs serve --dev-addr 0.0.0.0:8000 &

nohup でバックグラウンド実行。 & をつけてプロセスをバックグラウンドに移動させます。 実行後にターミナルを切っても、サーバーは動き続けます。 出力は nohup.out ファイルに保存されます。後で確認できます。

⚠️  mkdocs is already on your PATH and installed at /usr/bin/mkdocs. Downloading
    and running anyway.
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.05 seconds
INFO    -  [08:10:16] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [08:10:16] Serving on http://0.0.0.0:8000/
INFO    -  [08:10:23] Browser connected: http://192.168.11.204:8000/
INFO    -  [08:10:24] Browser connected: http://192.168.11.204:8000/

^CINFO    -  Shutting down...
root@mkdocs:~/my_mkdocs_project# nohup pipx run mkdocs serve --dev-addr 0.0.0.0:8000 &
[1] 6389
root@mkdocs:~/my_mkdocs_project# nohup: ignoring input and appending output to 'nohup.out'
  1. コンテナの自動起動設定 手順1: ProxmoxでCTの自動起動を設定 Proxmoxの管理インターフェースを使用して、CTがシステム再起動時に自動的に起動するように設定できます。

Proxmox管理画面にログイン 左側のメニューから 「CT」 を選択し、対象のコンテナをクリック 「オプション」 タブを開き、「自動起動」をクリック 「自動起動」 を 有効にする これで、Proxmoxホストが再起動した際に、CTも自動的に起動します。

手順2: コンテナ内でサービス（MkDocs）の自動起動設定 CT内でMkDocsサーバーを自動的に起動させる方法としては、systemd を使ってサービスを設定するのが一般的です。

  1. MkDocs用のSystemdサービスファイルを作成 コンテナ内で以下のサービスファイルを作成します。
sudo nano /etc/systemd/system/mkdocs.service

次の内容をサービスファイルに記述します： ini コピーする 編集する [Unit] Description=MkDocs Documentation Server After=network.target

[Service] Type=simple ExecStart=/usr/local/bin/mkdocs serve --dev-addr 0.0.0.0:8000 WorkingDirectory=/home/your_user_name/my_mkdocs_project Restart=always User=your_user_name Group=your_user_name

[Install] WantedBy=multi-user.target ExecStart には、MkDocsを起動するコマンドを記載します。/home/your_user_name/my_mkdocs_project はあなたのプロジェクトディレクトリに合わせて変更してください。 User と Group には、実行ユーザー（例えば、your_user_name）を指定します。 2. サービスを有効化して起動 サービスをリロードして新しいサービスを認識させます。

sudo systemctl daemon-reload

サービスを自動起動に設定します。

sudo systemctl enable mkdocs.service

サービスを開始します。

sudo systemctl start mkdocs.service
  1. サービスの状態確認 サービスが正しく起動したか確認するために、次のコマンドを実行します。
sudo systemctl status mkdocs.service

手順3: コンテナ再起動後に確認 コンテナを再起動して、MkDocsが自動的に起動するか確認します。

sudo reboot

再起動後に、コンテナ内で以下のコマンドを使ってサービスが正しく起動しているか確認します。

sudo systemctl status mkdocs.service

また、ブラウザでアクセスしてMkDocsのページが表示されることを確認します。

SSHサービスが起動しているか確認

CTのコンソール（ProxmoxのWeb GUI）からCTにログインし、以下のコマンドを実行してください。

systemctl status ssh

もし inactive (dead) または failed になっている場合、起動してください。

sudo systemctl start ssh

自動起動を有効にする場合は、以下も実行します。

sudo systemctl enable ssh

/etc/ssh/sshd_config の Port 22 がコメントアウトされているため、SSHのポートが無効になっている状態です。

以下の手順でポート22を有効にしましょう。

  1. 設定ファイルを編集 以下のコマンドでSSHの設定ファイルを開きます。
sudo nano /etc/ssh/sshd_config

ファイル内で #Port 22 という行を探し、コメント（#）を削除して有効にします。

- #Port 22
+ Port 22

2. SSHサービスを再起動

編集を保存 (Ctrl + X → Y → Enter) した後、SSHサービスを再起動します。

sudo systemctl restart ssh

再起動後、SSHが正常に動作しているか確認します。

sudo systemctl status ssh

active (running) になっていればOKです。

3. SSHのポート確認

デフォルトではポート22が使用されますが、変更されている可能性があるので、設定を確認します。

sudo cat /etc/ssh/sshd_config | grep "^Port"

もし Port 22 以外のポートが指定されていた場合、SSH接続時に明示的に指定してください。

ssh -p <ポート番号> <ユーザー名>@<CTのIPアドレス>

/etc/ssh/sshd_config

rootでログインを許可+公開鍵認証が必要

PermitRootLogin prohibit-password

rootでログインを許可+パスワードでログイン可能

PermitRootLogin yes PasswordAuthentication yes

クライアントマシン（接続元のマシン）で、SSH 鍵ペアを作成

ssh-keygen -t rsa -b 4096

SSH エージェントに鍵を追加(設定不要だった)

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa

公開鍵をサーバにコピー サーバ側は「PermitRootLogin prohibit-password」ではなく「PermitRootLogin yes」にする必要あり

ssh-copy-id root@192.168.11.204

ufwの設定

sudo apt update
sudo apt install ufw -y
systemctl status ufw
ufw allow 22/tcp
ufw allow 8000
ufw reload
systemctl status ufw

mkdocs を pipx でインストールした場合、Material for MkDocs を安全にセットアップする手順

pip install mkdocs-material

pipx で mkdocs をインストールしていることを確認 pipx list

mkdocs の仮想環境内で必要なパッケージをインストールする

pipx install mkdocs-material --include-deps

--include-deps オプション: 通常、pipx はアプリケーションのインストールのみを行いますが、--include-deps を指定すると、そのアプリケーションが依存しているパッケージも自動的にインストールされます。これにより、mkdocs-material に必要なすべての依存パッケージがまとめてインストールされ、動作に必要な環境が整います。

テーマを変えておかしくなったときは以下。 ただし、mkdocsの自動設定デーモンを作っておく必要アリ。

systemctl restart mkdocs

command

proxmoxでLCXコンテナの立ち上げ SSHキーを登録すると何も設定入れなくてもSSHできるようになる

コンテナにログインして、必要なパッケージをインストールします。 apt update && apt upgrade -y

venvとpipの導入 apt install -y python3-venv python3-pip

仮想環境作成 python3 -m venv ~/mkdocs-venv

MkDocsとMaterialテーマをインストール pip3 install mkdocs mkdocs-material

任意のディレクトリでMkDocsのプロジェクトを作成

mkdir ~/mkdocs_project && cd ~/mkdocs_project
mkdocs new .

mkdocsの接続テスト mkdocs serve --dev-addr=0.0.0.0:8000

githubと連携

gitとGitHub CLIをインストール apt install -y git gh

GitHub CLI で認証 gh auth login

リポジトリの作成 gh repo create RIB9/mkdocs_project --private --source=. --remote=origin （--private を --public に変えれば公開リポジトリになります。） --source=. は、現在のディレクトリをリポジトリとして使う 指示 --remote=origin は、Gitリモートを自動設定するオプション

SSHキーを作成

ssh-keygen -t ed25519
cat ~/.ssh/id_ed25519.pub

GitHubの「Settings」 → 「SSH and GPG keys」 → 「New SSH Key」 に追加。 https://github.com/settings/keys

SSH接続を設定

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

GitリモートURLを変更 git remote set-url origin git@github.com:RIB9/mkdocs_project.git

接続テスト ssh -T git@github.com

gitのユーザ登録 git config --global --edit

リポジトリにプッシュ

git remote add origin git@github.com:RIB9/mkdocs_project.git
git add .
git commit -m "Initial commit"
git push -u origin main

コンテナ再起動でMkDocs自動起動

systemd を設定 vi /etc/systemd/system/mkdocs.service

以下を記載 mkdocsのパスは仮想環境であることに注意

[Unit]
Description=MkDocs server
After=network.target

[Service]
ExecStart=/root/mkdocs-venv/bin/mkdocs serve --dev-addr=0.0.0.0:8000
WorkingDirectory=/root/mkdocs_project
Restart=always
User=root
Environment="PATH=/root/mkdocs-venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"

[Install]
WantedBy=multi-user.target

適用

systemctl daemon-reload
systemctl enable mkdocs
systemctl start mkdocs

テーマ適用

いろんなテーマ https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes

マテリアル https://github.com/squidfunk/mkdocs-material

公式 https://www.mkdocs.org/

Cloudflare

https://developers.cloudflare.com/pages/framework-guides/deploy-an-mkdocs-site/

環境変数 (詳細) > 変数の追加 > に移動し、値 が .PYTHON_VERSION3.7 ↑は実際の環境に合わせないとデプロイが失敗する（設定しないほうがうまくいった）