ブログとしてMkDocsを使う
Motivation
今年はブログを頑張って書こうとかなと思ってみたものの、以前の はてなブログ を使って書くのはどうも気がノリませんでした。 理由はあんまわからない...デザインのせいなんだろうか。
ちょうど以前、仕事で MkDocs を使ってドキュメントサイトを構築する機会があったのですが、 そのときにけっこう使いやすいなと感じていました。あの感覚でブログが書けたら楽しいのではないかと思い、MkDocs + GitHub Pagesでこのサイトを構築してみました。
なお、作ったことで既に若干満足していて、はたしてブログは書き続けるのだろうかという懸念が生じています。
MkDocsの導入
このあたりを参照すればわかると思いますので、割愛します。
https://www.mkdocs.org/getting-started/
Material for MkDocsを使用する
Material for MkDocs というテーマが、デザインも機能も充実していてとてもオススメです。前述した仕事でドキュメントサイトを作ったときにもこれを利用しました。 オススメです。
これも導入方法は割愛。
使用しているMarkdown Extension
Material for MkDocsには色々なMarkdown Extensionが用意されています。例えば Mermaid対応 もされています。
使用しているのはこんな感じ。
markdown_extensions:
- admonition # https://squidfunk.github.io/mkdocs-material/reference/admonitions/
- attr_list # for emoji and etc...
- meta # for navigation and etc...
- pymdownx.details # for admonition
- pymdownx.emoji: # https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#configuration
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
- pymdownx.highlight
- pymdownx.inlinehilite
- pymdownx.superfences:
custom_fences:
# https://squidfunk.github.io/mkdocs-material/reference/diagrams/
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
デザインの調整
フォント
デフォルトのフォントは Robot なので、日本語ではちと微妙です。 Noto Sans JP を使用するようにします。デザイナの同僚から教えてもらって以来、お気に入りのフォントです。
またソースコードのフォントには JetBrains Mono を利用します。自分が普段からJetBrainsのエディタを使用しているためです。
mkdocs.yml に以下のように指定します。
theme:
font: # https://squidfunk.github.io/mkdocs-material/setup/changing-the-fonts/
text: Noto Sans JP
code: JetBrains Mono
微調整
見出しのfont-weightがもうちょい太くあって欲しい等で、以下のようなCSSをdocs/stylesheets/extra.cssとして用意します。
h1, h2, h3, h4, h5, h6 {
font-weight: 700 !important;
}
h1 {
color: #000 !important;
}
h2 {
margin-top: 2.2em;
padding-bottom: 0.3em;
border-bottom: 0.02em solid #333;
}
/* header logの余白調整 */
.md-header__title {
margin-left: 0 !important;
}
/* navigation footerを非表示にする */
.md-footer__inner.md-grid {
display: none;
}
article.md-content__inner {
padding-bottom: 40px;
}
そして、mkdocs.yml に以下のように指定します。
extra_css:
- stylesheets/extra.css # https://squidfunk.github.io/mkdocs-material/customization/#additional-css
mkdocs-blogging-plugin
肝心のブログ機能ですが、mkdocs-blogging-plugin というのを使用しました。
類似のもいくつかあるようですが、一番シンプルそうなので直感でこれにしました。以下のように、ブログ記事として使用するdirectoryを指定すればOKです。
plugins:
# https://liang2kl.codes/mkdocs-blogging-plugin/
- blogging:
dirs:
- blog/article
size: 10
locale: ja_JP
ブログの目次ページは、以下のように1ファイル用意すればOK。
# Blog
{{ blog_conten }}
ページネーション等も用意されます。ただし、あくまでJSによる見せかけのページネーションなので、ブログ記事が1万件とかになったときに大丈夫なのだろうかという不安はある。まあ、1万件も書けるわけないので気にしないことにしました。
mkdocs-git-revision-date-localized-plugin
mkdocs-git-revision-date-localized-plugin を使うと、git logのtimestampから記事の更新時間を挿入することができます。
いちいち手で書くのはしんどいので、このpluginを使用することとしました。
plugins:
- git-revision-date-localized:
type: custom
custom_format: "%Y/%m/%d %H:%M"
timezone: Asia/Tokyo
exclude:
- index.md
- blog/index.md
やってないこと
metaタグとかOGPとかTwitter Card対応とかは全然していない。気が向いたらやる。 やった。
まとめ
というわけで、このサイトをこんな感じでMkDocsを使って作ってみました。
基本的にMkDocsおよびその周辺は手慣れているPythonで書かれているため、いざとなったら自分でなんとかすりゃええや〜という気軽さで使用できるのが個人的には良いかな。