MkDocs 使い方 Webページ作成にトライ ( Material theme )

2023-10-21

MkDocs でWebページ作成にトライ（テーマ：Material使用）。インストールやカスタマイズ方法・必要最低限のコマンドなどを忘れないよう自分の備忘録として残すことにしました（下記詳細）。

MkDocs とは?

MkDocsは、特にソフトウェア開発ドキュメントの作成に適した、静的サイトジェネレーターです。Markdownを使用してコンテンツを書き、リアルタイムでプレビューしながらプロジェクトドキュメントのウェブサイトを構築することができます。このツールはPythonで書かれており、シンプルさと使いやすさに重点を置いて設計されています。

MkDocsの主な特徴：

Markdownによるコンテンツ作成：
- MkDocsは、MarkdownファイルをHTMLに変換して、ウェブサイトのコンテンツを作成します。Markdownは学習が容易で、テキストベースの書式設定システムなので、多くの開発者にとって親しみやすいです。
テーマとカスタマイズ：
- さまざまなスタイルやレイアウトを備えたプリビルドのテーマが用意されており、これらはカスタマイズも可能です。さらに、ユーザー独自のテーマを作成し、適用することもできます。
サイト構築の自動化：
- MkDocsはコマンドラインツールであり、build コマンド一つでサイトの生成や更新が可能です。これにより、ドキュメントのメンテナンスが容易になります。
リアルタイムプレビュー（ライブリロード）：
- serve コマンドを使用すると、ローカルでウェブサイトをホストし、ドキュメントに加えた変更をリアルタイムでプレビューできます。ファイルに変更が加えられると、自動的にブラウザが更新されます。
検索機能の統合：
- 生成されたドキュメントサイトには、標準でフルテキスト検索機能が含まれています。これにより、エンドユーザーが必要な情報を簡単に見つけることができます。
プラグインシステム：
- 拡張機能やカスタマイズをサポートするためのプラグインシステムが用意されています。これにより、特定のニーズに合わせて機能を追加したり、既存の動作を変更したりすることができます。

PCの作業環境

PC：MacBook Pro (13インチ、M1、2020)
OS：macOS モントレー（ver12.6）
ターミナル：zsh
設定：ロゼッタ

注: Rosetta” for M1
Homebrew を使用してソフトウェアをインストールする場合、Intel 版 Homebrew と Arm 版 Homebrew でソフトウェアのインストールフォルダーが異なるため、一部のソフトウェアで起動の問題が発生しました。細かい制御で使用できるようですが、変更しました。私のコンピュータースキルと仕事の目的を考慮して、Mac の設定をロゼッタモードに変更しました。

MkDocsのインストールの流れ

まずfabcloudのSetting up MkDocsで学習してから、インストールしました

Homebrew（バージョン3.6.17）をインストール-> Homebrew
インストールされている Python (バージョン: 3.11.1)
インストールされた pip (バージョン 22.3.1)
インストールされた Mkdocs (バージョン 1.4.2)

Mkdocs をカスタマイズする

Mkdocs を見やすくするために、MkDocs テーマとMkDocs Configurationを参照の上、mkdocs.ymlのファイルを下記通りに変更しました　。

1) インストールテーマ「material」

pip を使用して MkDocs のマテリアルのテーマをインストールしました。

pip install mkdocs-material

2) MkDocs をカスタマイズする

mkdocs.ymlファイルに次のように編集して追加

サンプルコード

site_name: SAMPLE SITE

site_dir: "public"

theme:
  name: material

  features:
  - content.code.copy

  palette:
    primary: teal
    scheme: slate

# Copyright
copyright: Copyright © 20xx SAMPLE SITE