対象読者
MATLABのソースコードを含むドキュメントをMkDocsで作りたい人。
以下のようなページを作る方法を解説する。デフォルトだと，MATLABコードのシンタックスハイライトが機能しないので，そのあたりを解説する。
本記事の環境
- Python 3.10.11
- mkdocs 1.6.0
- mkdocs-material 9.5.33
準備
- （前提）pythonはインストール済みとする。
-
MkDocsをインストールする
pip install mkdocs -
mkdocs-materialをインストールする
pip install mkdocs-material
手順
- mkdocsで新規プロジェクトを作成する。プロジェクト名はここでは
sample_projectとする。以下のコマンドを打つと，カレントディレクトリ配下にsample_projectというフォルダができる。mkdocs new sample_project -
sample_project/docs/mkdocs.ymlファイルを以下のように編集する。mkdocs.ymlsite_name: My Docs theme: name: material features: - content.code.copy markdown_extensions: - pymdownx.highlight: anchor_linenums: true line_spans: __span pygments_lang_class: true - pymdownx.inlinehilite - pymdownx.snippets - pymdownx.superfences -
sample_project/docs/index.mdファイルにmatlabコードを記載する。- コードブロック
```の後にmatlabを追加して，言語を指定する - インラインコードの場合は
:::matlabか#!matlabを先頭につける - コード行数をつける場合は，
{.matlab linenums=1}とする。linumes=2とすると，先頭行が2から始まる。 - ファイル名をつける場合は,
{.matlab title="sample.m"}とする。 - ほかのオプションはmkdocs-materialのリファレンスを参照。
- 以下は冒頭の画像を作った時のサンプル。（プログラムはmathworksのヘルプから引用）
index.md# Welcome to MkDocs-MATLAB ```matlab % Create and plot a sphere with radius r. [x,y,z] = sphere; % Create a unit sphere. r = 2; surf(x*r,y*r,z*r) % Adjust each dimension and plot. axis equal % Use the same scale for each axis. % Find the surface area and volume. A = 4*pi*r^2; V = (4/3)*pi*r^3; ``` ## 行数表示+タイトル ```{.matlab linenums=1 title="sample.m" } % Create and plot a sphere with radius r. [x,y,z] = sphere; % Create a unit sphere. r = 2; surf(x*r,y*r,z*r) % Adjust each dimension and plot. axis equal % Use the same scale for each axis. % Find the surface area and volume. A = 4*pi*r^2; V = (4/3)*pi*r^3; ``` ## インライン表示 1. `:::matlab A = 4*pi*r^2;` 1. `#!matlab A = 4*pi*r^2;` - コードブロック
- プロジェクトフォルダに移動し，
mkdocs serveを行う。cd sample_project mkdocs serve -
http://127.0.0.1:8000/ を開くと以下の画像（冒頭の画像）が表示される。コメントが灰色になっていたり，関数が紫色になっていることがわかる。デフォルト（全部黒）よりは見やすくなっている。
補足
- 色が気に入らない場合はここを参考にすれば変更できる。
- matlabセッションのシンタックスハイライトをしたい場合は，
matlabの代わりにmatlabsessionを指定すると見た目が少し良くなる（参考）