MKDocsは、Markdown形式で書かれたテキストをWebサイトとして簡単に公開できるPython製の静的サイトジェネレーターです。
本記事では、MKDocsの基本的な使い方からカスタマイズ、活用例、さらに実際のWebページ作成例までを詳しく解説します。
ドキュメントサイトやブログを簡単に作りたい方におすすめです！
生成AIが発達して様々なマークダウン形式のコンテンツが増えました！
Pythonの環境でMarkdown形式を用いてWebページを簡単に作る方法ってありますか？
それなら「MKDocs」がおすすめですよ！
PythonでJupyter NotebookやGoogle Colaboratoryを使っている方は違和感なく使っていただけます！
また、HTMLやCSSなどの知識も不要なので利用してみてください！
MKDocsとは？
MKDocsは、Markdownベースの記述でWebページを作成するためのツールです。
Markdownで簡単に書けるだけでなく、きれいなデザインテンプレートや高速なビルド性能を持つため、多くの開発者やブロガーに支持されています。
MKDocsの主な特徴
- Markdownで簡単記述
- HTMLやCSSの知識は不要。
- 普段Markdownを書く感覚でサイトを作成できます。
- 豊富なデザインテンプレート
- 「Material for MKDocs」など、モダンで美しいテーマが利用可能。
- 軽量かつ高速
- 静的なHTMLファイルを生成するため、サイト構築が非常に高速。
- 生成後はWebサーバーにアップロードするだけで公開可能。
- 柔軟なカスタマイズ
- YAML形式の設定ファイル（
mkdocs.yml）を使って、簡単にデザインやナビゲーションを調整可能。
- YAML形式の設定ファイル（
インストール方法
MKDocsはPython製なので、Python環境が必要です。
以下の手順でインストールを行います。
次のコマンドを実行してインストールします：
pip install mkdocsインストール後、以下のコマンドでバージョンを確認してください：
mkdocs --version基本的な使い方
MKDocsを使ったサイト構築は非常に簡単で、以下の手順で進められます。
1. プロジェクトの作成
次のコマンドで新しいプロジェクトを作成します：
mkdocs new my-project
cd my-projectmy-project という名前のフォルダが作成され、以下の初期ファイルが自動生成されます：
mkdocs.yml: サイト全体の設定を行う設定ファイル。docsフォルダ: Markdownファイルを置くディレクトリ。
2. ローカルプレビュー
開発サーバーを起動して、サイトをローカルで確認できます：
mkdocs serve- ブラウザで
http://127.0.0.1:8000にアクセスするとプレビューが確認できます。 - ファイルを編集すると、自動で変更が反映されるため非常に便利です。
3. サイトの構築
最終的に静的なHTMLファイルを生成するには、以下を実行します：
mkdocs build- 生成されたHTMLファイルは
siteフォルダ内に保存されます。 - このフォルダをサーバーにアップロードするだけでサイトを公開できます。
Markdownの記述例
Markdownを使うことで、見出しやリスト、コードブロックなどを簡単に記述できます。
見出しの作成
# 見出し1
## 見出し2
### 見出し3リンクの作成
[MKDocs公式サイト](https://www.mkdocs.org)
リストの作成
- 箇条書き1
- 箇条書き2
- サブ項目
1. 番号付きリスト1
2. 番号付きリスト2コードブロック
def hello_world():
print("Hello, World!")実際のWebページ作成例
ここでは、シンプルなドキュメントサイトを作成する例を紹介します。
プロジェクトの構造
以下のような構造を持つプロジェクトを作成します：
my-project/
├── mkdocs.yml
└── docs/
├── index.md
├── about.md
└── contact.md各ファイルの内容
mkdocs.yml
サイトの設定を定義します。
site_name: My Awesome Site
theme:
name: material
nav:
- Home: index.md
- About: about.md
- Contact: contact.mddocs/index.md
ホームページの内容をMarkdownで記述します。
# Welcome to My Awesome Site!
This is the home page of the site. Navigate using the links above.
- [About](about.md)
- [Contact](contact.md)docs/about.md
サイトの「About」ページを記述します。
# About This Site
This site was created using [MKDocs](https://www.mkdocs.org) with the Material theme.
## Features
- Simple and fast
- Easy to customize
- Markdown-baseddocs/contact.md
「Contact」ページを記述します。
# Contact Us
Feel free to reach out to us:
- **Email**: contact@example.com
- **Phone**: +123-456-7890
- **Address**: 123 Main Street, Hometown, Countryローカルでの確認
以下のコマンドを実行して、ローカルで確認します：
mkdocs serveブラウザで http://127.0.0.1:8000 にアクセスすると、以下のようなナビゲーション付きのWebページが表示されます：
- Home
- About
- Contact
サイトの公開
サイトを構築して公開するには、以下を実行します：
mkdocs buildsite フォルダ内に生成されたHTMLファイルをサーバーにアップロードすることで、インターネット上で公開できます。
GitHub Pagesへのデプロイ
MKDocsで作成したサイトをGitHub Pagesを使って簡単に公開できます。
デプロイ手順
- GitHubにリポジトリを作成。
- 次のコマンドでデプロイを実行：
mkdocs gh-deployこれだけで、GitHub Pages上にサイトが公開されます。
まとめ
MKDocsを使えば、Markdownを利用して短時間で美しいWebページを作成できます。以下のような特徴を持つMKDocsは、ドキュメントサイトや個人用ブログの作成に最適です：
- HTMLやCSSの知識が不要
- 高速な構築とシンプルな公開手順
- デザイン性と機能性を兼ね備えたテーマ
簡単な例から始めて、あなたのプロジェクトに役立つドキュメントサイトを作成してみてください！
本ブログ「ゴマフリーダムのPython教室」のトップページへは以下へアクセス！
コメント