MkDocsで簡単サイト作成

はじめに

簡単に共有用のサイトを作りたいけど、htmlやcss,jsを書くのはめんどくさいし、Markdownでちゃちゃっと書いてそれなりの見た目で公開できないかな。と思いませんか？

MkDocs(+ Material for MkDocs)で可能だったのでまとめます。

デモサイト

導入

bash

pip install mkdocs
pip install mkdocs-material

新しいPJを作成

bash

mkdocs new .

以下のような感じになります。

フォルダ構成

.
├─ docs/
│  └─ index.md
└─ mkdocs.yml

設定

下記のように記載するとマテリアルテーマを利用できます。

mkdocs.yml

theme:
  name: material

※その他機能を有効にするにはこちらのファイルに追加していく必要があります。

使い方

index.mdに記載をしていきます。(ファイル名は任意で問題なし)
複数ページ作りたい時は複数ファイルを作るだけで自動で目次リンク付きのサイドバーを生成してくれます。

sample.md

# サンプルページです

## MkDocs便利！

基本的にはリファレンスページの通りで問題ないですが、一部スポンサーのみ(15ドル/月の援助※)の機能があるので注意です。

個人的にはGridが使えないのが痛いですね。。(14,000ドルに到達すれば開放される模様。現在9,900ドル。。※)

※いずれも2022/11/22現在

ローカルサーバで確認

bash

mkdocs serve

ビルド(htmlなど、各種ファイルの生成)

bash

mkdocs build

GitHubPagesにデプロイする

専用コマンドが用意されています。

bash

mkdocs gh-deploy

Tips

独自のCSS,JSを利用したい場合は以下を追加
(階層とファイル名は任意に設定可能)

mkdocs.yml

extra_css:
  - stylesheets/extra.css
extra_javascript:
  - javascripts/extra.js

また、マークダウンファイルの中にhtmlも書けるので、MkDocksの機能を使いつつ自由度の高いサイト作りも可能です。