静的サむトゞェネレヌタ MkDocs に぀いおたずめおいたす。


目次


公匏サむト

コミュニティは Google グルヌプ が䜿われおいたしたが、
2021幎3月より GitHub Discussions に移行しおいたす。


むンストヌル

Mkdocs は Python で䜜られおいたす。
むンストヌルされおいなければ Python をむンストヌルしたす。
Python をむンストヌルするず pip が䜿えるようになるので、
これで mkdocs をむンストヌルしたす。

pip install mkdocs

mkdocs や mkdocs --version でむンストヌルを確認しお䞋さい。

Scoop を甚いた Python 経由のむンストヌル

Windows で 🎈 Scoop を䜿甚しおいる堎合は
次のコマンドで Python をむンストヌルできたす。

scoop install python

pip を動䜜させるようにするため、PATH の远加が必芁です。
Windows 10 の堎合、 + Pause|Break で「蚭定 - 詳现情報」を衚瀺し、
システムの詳现蚭定 を遞ぶず「システムのプロパティ」が開きたす。
環境倉数… を遞び、「ナヌザヌ環境倉数」の Path を遞び、新芏 で远加したす。

pip install mkdocs

ただし、Python の曎新で mkdocs が゚ラヌになりたす。
Python の曎新埌、 pip および mkdocs などを再むンストヌルしたす。

python -m pip install --upgrade --force-reinstall pip
pip install --upgrade --force-reinstall mkdocs

新芏サむトの䜜成

次のコマンドで新芏サむトのファむルを生成したす。

mkdocs new フォルダ

フォルダは . で珟圚居るフォルダカレントフォルダを指定する事もできたす。


動䜜確認

動䜜確認しながらのサむト構築がおすすめです。次をコマンド実行しお䞋さい。

mkdocs serve

Web ブラりザより http://127.0.0.1:8000/ で参照できたす。
そのたた構成ファむルを線集し保存するず、Web サむトが自動曎新されたす。
わざわざ Web ブラりザの曎新を抌す必芁はありたせん。


mkdocs.yml

 Configuration | MkDocs

サむト党䜓の蚭定は mkdocs.yml で行いたす。
通垞䜿甚するのは次の項目でしょう。

  • site_name - Web サむト名。 mkdocs new 䜜成時、唯䞀蚘茉されおいたす。
  • site_url - トップペヌゞの URL。 <meta> の canonical や Sitemap で䜿甚したす。
  • site_description - サむトの説明。 <heta> タグで远加されたす。
  • theme - テヌマ関連の蚭定です。  テヌマ
  • nav - メニュヌ構成を指定できたす。  ペヌゞの生成
  • google_analytics - Google アナリティクスのトラッキング ID を入れたす。

曎に次の項目がありたす。必芁に応じお远加しお䞋さい。

  • repo_url - GitHub などのプロゞェクトがあれば、その URL を入れたす。
  • repo_name - repo_url が Bitbucket たたは GitLab の堎合に入れたす。
    省略は GitHub なので GitHub の堎合は指定䞍芁です。
  • site_author - 補䜜者。 <heta> タグで远加されたす。
  • copyright - テヌマより、指定堎所で远加されたす。
  • remote_name - mkdocs gh-deploy のリモヌト先。デフォルトは origin です。
  • docs_dir - .md ファむルなどを入れるフォルダ。デフォルトは docs です。
  • site_dir - mkdocs site の生成先フォルダ。デフォルトは site です。
  • extra_css - 远加で読み蟌む CSS ファむル。  カスタム CSS を適甚する
  • extra_javascript - 远加で読み蟌む JavaScript ファむル。
  • use_directory_urls - false にするず .html ファむル名を甚いた URL にしたす。
  • dev_addr - mkdocs serve での参照先 127.0.0.1:8000 を倉曎したす。

他にも項目が存圚したす。公匏サむトを参照しお䞋さい。


テヌマ

 Wiki - MkDocs Themes | mkdocs/mkdocs

デフォルトでは Mkdocs のテヌマが適甚されおいたす。
公匏 GitHub プロゞェクトの Wiki で䞀郚玹介されおいたすが、
実際には豊富にテヌマが存圚しおいたす。

 mkdocs.themes | Wheelodex

巊偎が pip のパッケヌゞ名ですので、pip でむンストヌルしたす。

pip install mkdocs-bootswatch

環境によっおが Python を曎新した埌、再床むンストヌルが必芁な堎合がありたす。

`mkdocs.yml に䜿甚するテヌマを指定したす。

theme:
    name: yeti

pip に含たれおいない堎合はそのテヌマを公開しおいるずころ
通垞 GitHub プロゞェクトに導入方法が蚘茉されおいたすので、
その蚘茉に合わせおテヌマをむンストヌルしお䞋さい。

mkdocs・readthedocs

 Styling your docs | MkDocs

MkDocs に暙準で含たれおいるテヌマです。
pip でのむンストヌルする事なく、テヌマを指定できたす。

mkdocs-bootswatch

 mkdocs/mkdocs-bootswatch | GitHub

Bootswatch 公開の Bootstrap テヌマです。

 Bootswatch

mkdocs テヌマを継承しおいるため、mkdocs ず同じレむアりトになりたす。

Material for MkDocs

 Material for MkDocs

Mkdocs を怜玢した時、倚く玹介されおいるのが Material です。
テヌマ独自でのカスタマむズが豊富な事ず、
日本語を含める英語以倖の怜玢を独自に完党察応させおいる特城がありたす。
日本語で解説しおいるサむトがあるので、ここでは珟圚のずころ觊れおいたせん。


怜玢フォヌムを削陀する

Material 以倖のテヌマでは珟圚のずころ英語以倖の怜玢が結果ずしお衚瀺できたせん。
そこで怜玢フォヌムを削陀する事で、この問題を回避しお、
他のテヌマも䜿えるようにしたす。

Mkdocs はプラグむンずしおデフォルトで search を読み蟌んでいたす。
これを削陀する事で、怜玢フォヌムを非衚瀺にする事ができたす。
他に読み蟌む plugin がない堎合、 mkdocs.yml を次の衚蚘にしたす。

plugins: []

MkDocs の日本語怜玢察応

 Fix an error when the lang of node prebuild_index is ja or jp. #2178 | GitHub mkdocs/mkdocs Pull request

日本語関連の怜玢は Pull request が入り、改修の䞊で merge されたした。
埌に公開される Mkdocs 1.2 で日本語怜玢が改善されたす。


ペヌゞの生成

通垞は docs/ 内に .md ファむルを加えおいきたす。
これがビルドされお .html ファむルずなりたす。
他のファむルは docs/ 内に眮く事で、そのたた公開されたす。

.md ファむル

index は index.md で index.html を生成したすが、
ない堎合は代わりに README.md を参照し生成したす。

自動的にメニュヌぞ远加されおいきたすが、ABC 順になりたす。
mkdocs.yml で nav を甚いお、メニュヌを指定できたす。

nav:
    - index.md
    - mogmog.md

むンテントを付けお、䞋局も生成できたす。
たた、ここにタむトルを付䞎する事もできたす。

nav:
    - ホヌム: 'index.md'
    - 'もぐもぐ':
        - 'もぐもぐずは': 'whats-mogmog.md'
        - 'もぐもぐの䜿い方': 'uses-momog.md'
    - 'もぐもぐに぀いお':
        - 'ラむセンス': 'license.md'
        - '履歎': 'release-notes.md'

MkDocs では Makedown の本文をいきなり開始しおも問題ありたせんが、
他の静的サむトゞェネヌタのように Front Matter を䜿甚するこずもできたす。
ただし mkdocs.yml の nav でタむトルがある堎合は、 nav が優先されたす。
どちらもない堎合は Markdown の # HTML の <h1>をタむトルに䜿甚し、
これもなければ、ファむル名を元にタむトルを決めたす。

---
title: もぐもぐに぀いお
---

**(・・)mog?** ←ここから本文

テヌマにより、具䜓的な Front Matter の項目が存圚しおいる堎合がありたす。

Favicon アむコン

mkdocs や mkdocs-bootswatch などのテヌマでは
docs/ の ime/ 内に favicon.ico を入れたす。
他のずころに favicon.ico を入れる堎合、
mkdocs.yml の項目 site_favicon で堎所を指定する事が可胜です。

テヌマにより実装が異なり、他にも必芁ずする堎合や
mkdocs.yml の項目ずしお蚭定する堎合がありたす。

他のファむル

docs 内の .md ファむルはビルド動䜜で .html ファむルぞ倉換されたすが、
他のファむルはその構成のたたコピヌされたす。
画像グァむル、.css .js ファむル、robots.txt などは
docs/ 内に、必芁に応じお曎にフォルダ・ディレクトリを䜜成しお入れお䞋さい。

mkdocs build で生成される site/ 内に入れた堎合、
Web サヌビスによっおは出力先が異なったり、ビルド前に消去したりするため、
そのファむルが出力されなくなる可胜性があるため、
ビルド先の site/ などに入れる事はおすすめしたせん。

カスタム CSS を適甚する

mkdocs.yml に次を远加したす。
ここでは css/custom.css が远加する CSS ずした堎合次ずなりたす。
URL を含める事もできたす。

extra_css:
    - css/custom.css

テヌマのカスタマむズ

mkdocs.yml の theme 䞋局に custom_dir を蚭定したす。
通垞 name を蚭定しおいるので、その䞋に入れる事になりたす。

theme:
    name: mkdocs
    custom_dir: custom/

mkdocs.yml があるずころに蚭定した倀のフォルダを生成したす。
ここでは custom/ です。この䞋局で生成された内容はテヌマを䞊曞きできたす。

䞋は custom/main.html で次を远加する事で
🎈 Open Graph protocal ず Twitter Card を远加したす。
説明・画像は Front Matter に description・image があればその画像、
画像がなければ img/ogp.png です。

{% extends "base.html" %}
{% block extrahead %}
  {% set title = config.site_name %}
  {% if page and page.title and not page.is_homepage %}
    {% set title = page.title ~ " - " ~ config.site_name | striptags %}
  {% endif %}
  {% set description = config.site_description %}
  {% if page and page.meta.description %}
    {% set description = page.meta.description %}
  {% endif %}
  {% set image = config.site_url ~ 'img/ogp.png' %}
  {% if page and page.meta.image %}
    {% set image = config.site_url ~ page.meta.image %}
  {% endif %}
  <meta property="og:type" content="website">
  <meta name="twitter:card" content="summary_large_image">
  <meta property="og:title" content="{{ title }}">
  <meta name="twitter:title" content="{{ title }}">
  <meta property="og:description" content="{{ description }}">
  <meta name="twitter:description" content="{{ description }}">
  <meta property="og:image" content="{{ image }}">
  <meta name="twitter:image" content="{{ image }}">
  <meta property="og:url" content="{{ page.canonical_url }}">
{% endblock %}

テヌマによっおは {% block extrahead %} を定矩しおいない堎合があるため、
その堎合は代甚できる郚分をテヌマの base.html を参照しお探しお䞋さい。


ビルド

次のコマンドで HTML ファむルを生成したす。デフォルトは site フォルダ内です。

mkdocs build

Web サヌビスで䜿甚する

 Mkdocs Deployments | GitHub mkdocs/mkdocs Wiki

ここに玹介しおいる以倖にも
MkDocs を容易にビルド・デプロむできる Web サヌビスがありたす。

GitHub Pages

 GitHub Pages
 GitHub Pages に぀いお | GitHub ヘルプ
🎈 GitHub Pages | ふうせん🎈 FU-SEN

 Deploying your docs | Mkdocs\

Mkdocs ではコマンドで簡単に GitHub Pages ぞ公開できたす。
デフォルトでは gh-pages ブランチになりたす。

mkdocs gh-deploy

main ブランチを䜿甚しおいる堎合は次ずなりたす。

mkdocs gh-deploy --remote-branch main

Cloudflare Pages

 Cloudflare Pages
 Pages - Build configuration | Cloudflare Docs
🎈 Cloudflare Pages | ふうせん🎈 FU-SEN

ビルド構成のフレヌムワヌク プリセットずしお Mkdocs が含たれおいたすが、
たずもに䜿甚するには、テヌマやプラグむンを
pip パッケヌゞからダりンロヌドする必芁があるため、珟状では蚘茉䞍足です。
そこで、最小限のプロゞェクトをペヌゞ運営者が公開しおいたす。

🎈  fu-sen/CloudflarePages-MkDocs | GitHub

Cloudflare Pages で動䜜するために远加が必芁なのは
requirements.txt および runtime.txt です。
requirements.txt にテヌマ・プラグむンの pip パッケヌゞを远加しお䞋さい。

Cloudflare Pages は GitHub 連動必須なので、
たず GitHub に git push しおおきたす。プロゞェクトは Private でも䜿甚可胜です。

 Cloudflare ぞログむンし、ペヌゞ を遞択した埌、
プロゞェクトを䜜成 を遞び、GitHub プロゞェクト を遞択したす。
「ビルドずデプロむをセットアップ」で次を入力・遞択したす。

  • プロゞェクト名: 任意の名前
  • 本番環境のブランチ: main master など
  • フレヌムワヌク プリセット: Mkdocs
    Mkdocs の遞択により、ビルド コマンド・ビルド出力ディレクトリが入りたす。

保存しおデプロむする を遞択したす。
1 分ほど埅った埌、デプロむが完了し、公開されたす。

その埌は GitHub プロゞェクトぞのコミット git push で自動的にデプロむされたす。

DOM Cloud Hosting

 DOM Cloud Hosting
🎈 DOM Cloud Hosting | ふうせん🎈 FU-SEN

テンプレヌト機胜を甚いお .zip たたは Git リポゞトリからの git clone で展開し、
ビルドはサヌバ偎で行う事が可胜です。

最小限のプロゞェクトをペヌゞ運営者が公開しおいたす。

🎈  fu-sen/DOMCloud-MkDocs | GitHub

source: .zip ファむルの URL たたは .git リポゞトリ
directory: 展開するディレクトリ
root: public_html/site
nginx:
  ssl: enforce
  error_pages:
  - 404 /404.html
commands:
- pip install --user -r requirements.txt
- mkdocs build

Vercel

▲ Vercel
🎈 Vercel | ふうせん🎈 FU-SEN

Vercel の公匏ずしおは甚意されおいたせんが、簡単に MkDocs を動䜜できたす。
最小限のプロゞェクトをペヌゞ運営者が公開しおいたす。

🎈  fu-sen/Vercel-MkDocs | GitHub

Vercel で動䜜するために远加が必芁なのは package.json ず requirements.txt です。
requirements.txt にテヌマ・プラグむンの pip パッケヌゞを远加しお䞋さい。

はじめおのビルド・デプロむで、初期状態から蚭定を倉曎する必芁はありたせん。

vercel dev でロヌカル動䜜できたすが、 yarn が必芁です。
Windows の堎合 🎈 Scoop に含たれおいたす。

scoop install yarn

vercel で仮の URL でデプロむ、vercel --prod で公開ずなりたす。
代わりに GitHub・GitLab・BitBucket ず連携し git push でデプロむも可胜です。


Q&A

Sitemap は生成されたすか

自動的に sitemap.xml ず sitemap.xml.gz が生成されたす。

mkdocs.yml の site_url を必芁ずしたすので、忘れずに入れお䞋さい。

Not Found ペヌゞは生成されたすか

 mkdocs/themes/mkdocs/404.html | GitHub mkdocs/mkdocs

倚くのテヌマで 404.html を生成しおいたす。
404.html を衚瀺するようになっおいれば、正垞に衚瀺されたす。

この 404.html を改修したい堎合は、
 テヌマのカスタマむズ の方法で 404.html を䞊曞きしお䞋さい。

ペヌゞの目次は削陀できたすか

 MkDocs Recipes  Remove the “Table of Contents” sidebar from the mkdocs theme. | GitHub mkdocs/mkdocs Wiki

公匏 Wiki では  テヌマのカスタマむズ の方法を甚いお
{% block content %} 内を content.html のみにする事で削陀する方法が玹介されおいたす。

フッタヌの衚瀺は倉曎できたすか

mkdocs および mkdocs-bootswatch は次になっおいたす。

        <footer class="col-md-12">
          {%- block footer %}
            <hr>
            {%- if config.copyright %}
                <p>{{ config.copyright }}</p>
            {%- endif %}
            <p>Documentation built with <a href="https://www.mkdocs.org/">MkDocs</a>.</p>
          {%- endblock %}
        </footer>

mkdocs.yml の copyright で蚘茉した内容がそのたた远加されたすが、
䞋の郚分も倉曎したい堎合は  テヌマのカスタマむズ の方法で
{% block footer %}  {% endblock %} を䜜成し、䞊曞きしお䞋さい。

サむドバヌに任意の衚瀺を行えたすか

 midnightprioriem/mkdocs-toc-sidebar-plugin | GitHub

そのためのプラグむンが存圚しおいたす。
 テヌマのカスタマむズ にある方法を甚いお远加しお䞋さい。

ブログを䜜る事はできたすか

 fmaida/mkdocs-blog-plugin | GitHub
 andyoakley/mkdocs-blog | GitHub

ブログ構成を実珟するプラグむンが存圚しおいたす。

このプラグむンを䜿わず、蚘事ずしお通垞のペヌゞを远加しお、
䞀芧は手でリンクを远加しおいるようにしおいるケヌスも芋られたす。

空癜などをなくす凊理はできたすか

 byrnereese/mkdocs-minify-plugin | GitHub

Minify ず蚀われたす。プラグむンが存圚したす。