なぜ MKDocs なのか？

何としても、md記法で書いたテキストを公開したいと思っているのですが、先に公開したMDwikiには検索もないし、ちょっと機能が足りないと思って、探したのがこのMKDocsです。

どこが異なるのか？

両者とも mdファイルを扱うのですが、異なるのは、MKdocs が index.md を元に手元でビルド、出来上がったindex.htmlをサイトにアップロードという手順を踏む（mdファイルはこの時点で不要となる。）のですが、MDwikiはサーバサイドで、index.md → index.html 変換して表示するという点です。その分 CPU に負担がかかるので、表示に若干遅い傾向にあります。

注意点としては、手元で build するために、サーバーサイドと同じ環境（例えば、extention やら plugin など）を手元に用意する必要があります。自宅サーバーを運営している身としては、「どちらにも同じ環境を用意することは無駄！」という意識が時々出ます。

両者の長短にについては、Markdown を HTML で読む手段として MkDocs と MDwiki を試したので優劣を書くに詳しい。

使い始めたばかりなので、まだまだですが、使い方を覚えながらこのサイトを更新していこうと思います。

まずは以下のページに記載のとおりをやってみました。

mkdocs.orgのGetting Started with MkDocsのページです。

インストール

ArchLinuxの場合、パッケージが用意されているので、以下のコマンドだけでインストールできます。

$ sudo pacman -S mkdocs

インストールされたのは、ver 1.6.1 です。

$ mkdocs --version
mkdocs, version 1.6.1 from /usr/lib/python3.14/site-packages/mkdocs (Python 3.14)

Commands

• mkdocs new [dir-name] - Create a new project.
• mkdocs serve - Start the live-reloading docs server.
• mkdocs build - Build the documentation site.
• mkdocs -h - Print help message and exit.

Project layout

mkdocs.yml    # The configuration file.（サイト全体の設定ファイル）
docs/
    index.md  # The documentation homepage.（ページの原本MDファイル（
    ...       # Other markdown pages, images and other files.

サイトにアップロードするファイル

プロジェクト名の下部に site というディレクトリが出来上がっていますので、この site ディレクトリの中身です。

└── my-project
    ├── docs
    │   └── index.md
    ├── mkdocs.yml
    └── site
        ├── 404.html
        ├── css
        │   ├── base.css
        │   ├── bootstrap.min.css
        │   ├── bootstrap.min.css.map
        │   ├── brands.min.css
        │   ├── fontawesome.min.css
        │   ├── solid.min.css
        │   └── v4-font-face.min.css
        ├── img
        │   ├── favicon.ico
        │   └── grid.png
        ├── index.html
        ├── js
        │   ├── base.js
        │   ├── bootstrap.bundle.min.js
        │   ├── bootstrap.bundle.min.js.map
        │   └── darkmode.js
        ├── search
        │   ├── lunr.js
        │   ├── main.js
        │   ├── search_index.json
        │   └── worker.js
        ├── sitemap.xml
        ├── sitemap.xml.gz
        └── webfonts
            ├── fa-brands-400.ttf
            ├── fa-brands-400.woff2
            ├── fa-regular-400.ttf
            ├── fa-regular-400.woff2
            ├── fa-solid-900.ttf
            ├── fa-solid-900.woff2
            ├── fa-v4compatibility.ttf
            └── fa-v4compatibility.woff2

結果は？