Skip to content

え？！私のサイトダサすぎ……！？

先日、MkDocsを使ってサイトを作るという題目でこのサイトを作成しました。
ドキュメント作成のためのMkDocsを使ってサイトを作成しているので、「それはそう」という感じではあります。
ある程度質素な見た目になることはわかっていました。
しかし、実際に読んでみると、ドキュメントとしては十分ですが、個人サイトと呼ぶには少し質素だと感じました。

MkDocsとMaterial for MkDocsのことを批判するつもりはないし、テンプレに乗ってるのに、自我を出そうとしている自分が悪いというのも十分承知をしています。 しかし、自前でHTMLとCSSを用意してる人は自分の世界観を表現できています。

MarkdownからHTMLを生成するためだけにこの構成を選択してるのですが、MkDocsについても、Material for MkDocsについても、全然詳しくないためその二つの学習も含めて、今回はこのサイトの見た目を少しずつ改善していきます。

KuretaNoneで解決したい問題とは別で、現状でも別に問題はないけど、どうせなら華やかにしたいよね、という感じです。

なのでここからは

上記の2つが、導入するされていることを前提に書いていきます。 どっちの機能か、はずかしい話自分でもまだわかっていないのでごっちゃになると思いますが、そこはご容赦ください。 (そこはわかるように調べろよという指摘はもっともですが、大事なのは結果と経験です。)

ソーシャルリンクとアイコンをつける

フッターにソーシャルリンクを付けるために mkdocs.ymlのextraに以下のように追加します。

extra:
  homepage: https://KuretaNone.net
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/KuretaNone
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/KuretaNone
    - icon: fontawesome/brands/youtube
      link: https://www.youtube.com/@KuretaNone

1749481801.png

フッターにGitHubのアイコンが追加されました。かわいいですね。

mkdocsの表示を消す

フッターのMade with Material for MkDocsの表示を消したい場合は、mkdocs.ymlのthemeに以下のように追加します。

extra:
  generator: false

1749483752.png 1749483970.png

コピーライトをつける

著作権表示を付けます

copyright: "© 2025 KuretaNone"

1749484120.png

フッターに著作権表示が追加されました。

ヘッダーを隠す

ヘッダーを隠すためには、mkdocs.ymlのthemeに以下のように追加します。

theme:
  features:
    - header.autohide

画像や表にキャプションを付ける

画像をはりつけたときに説明として、キャプションを表示したいですよね？

markdown_extensions:
  - pymdownx.blocks.caption

キャプションを付けるにはちょっと特殊な書き方をします。 これはObsidianとの互換性がないため、注意が必要です。

コード

![1749569652.png](../res/1749569652.png)

/// caption
example caption
///

結果

1749569652.png

example caption

フォントを変更する。

使用するフォントを本文とコードブロックで変更できます。

theme:
  font:
    text: Noto Sans JP
    code: Source Code Pro

結果

平文では、Noto Sans JPが使用され、コードブロックではSource Code Proが使用されてることがわかります

1749572930.png

1749572949.png

ccsをつける

docsフォルダの直下にcssフォルダを作成し、custom.cssを作成します。
mkdocs.ymlのextra_cssに以下のように追加します。

extra_css:
  - css/custom.css

h2とh3で区切りをつける

区切りがあると格段に読みやすいと思います。
僕はMarkdownのソースで下線をあまりひかないので、CSSで引いてもらおうと思います。

.md-typeset h2 {
  border-bottom: 1px solid gray;
}

リンクカードを導入する。

Material for MkDocs の機能の一つで、リンクカードを導入します。
Material for MkDocsの中ではSocial caerdsと呼ばれています。

mkdocs.ymlのpluginsに以下のように追加します。

plugins:
  - social

Caution

site_urlが設定されいてる必要があります。

また、リンクに日本語が含まれていると、デフォルトのRobotoフォントは対応していないため、Noto Sans JPを使用することをおすすめします。

plugins:
  - social:
      cards_layout_options:
        font_family: Noto Sans JP

実際に導入をしようとするとMkDocs serveをたたくと、 私の環境だと下記のようなエラーがでました。

エラー

(.venv) PS D:\KuretaNone> mkdocs serve
INFO    -  Building documentation...
ERROR   -  Required dependencies of "social" plugin not found:
           - ModuleNotFoundError("No module named 'PIL'")
           - ModuleNotFoundError("No module named 'cairosvg'")

           --> Install with: pip install "mkdocs-material[imaging]"

ライブラリが見つからないということなので、足してくれということですね。

pip install "mkdocs-material[imaging]"

今度は下記のエラーがでました。

(.venv) PS D:\KuretaNone> mkdocs serve
INFO    -  Building documentation...
ERROR   -  "cairosvg" Python module is installed, but it crashed with:
           no library called "cairo-2" was found
           no library called "cairo" was found
           no library called "libcairo-2" was found
           cannot load library 'libcairo.so.2': error 0x7e.  Additionally, ctypes.util.find_library() did not
           manage to locate a library called 'libcairo.so.2'
           cannot load library 'libcairo.2.dylib': error 0x7e.  Additionally, ctypes.util.find_library() did not
           manage to locate a library called 'libcairo.2.dylib'
           cannot load library 'libcairo-2.dll': error 0x7e.  Additionally, ctypes.util.find_library() did not
           manage to locate a library called 'libcairo-2.dll'

           --> Check out the troubleshooting guide: https://t.ly/MfX6u

Aborted with a BuildError!

どうやらcairoというライブラリが必要なようです。
今度も案内に従おうと思いましたが、cairoのdownloadページから、Windows用のバイナリのダウンロード先はリンクが死んでました。

Note

このエラーは、Pythonモジュール「cairosvg」はインストールされているものの、「libcairo」というシステムライブラリが見つからない・読み込めないために発生しています。
cairosvgは画像生成のために、Python以外の「cairo」ライブラリが必要です。

cairoのインストール

  1. cairoのインストール（Windows）

  2. 以下のページから「DLL」(Windows用)をダウンロード

  3. ダウンロードしたフォルダのbinフォルダにlibcairo-2.dllがあるので、ここにパスを通す 

    $env:Path += ";C:\Program Files\GTK3-Runtime Win64\bin"

  4. mkdocsの再起動 

    (.venv) PS D:\KuretaNone> mkdocs serve

まとめ

最後に少しだけ手間どってしまいましたが、これからも少しずつ、見た目や構成を改善して、見やすいサイト作りをしていきたいですね。
いずれはコメント機能を付けたり「あなたは何番目の訪問者です」とかつけたいです。

参考

Links to this page