MkDocsでMATLABコードのシンタックスハイライトを有効にする 

## 対象読者
MATLABのソースコードを含むドキュメントをMkDocsで作りたい人。

以下のようなページを作る方法を解説する。デフォルトだと，MATLABコードのシンタックスハイライトが機能しないので，そのあたりを解説する。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/260124/86a7a27c-5b4a-bd5c-884e-78e48f453a35.png)

## 本記事の環境
- Python 3.10.11
    - mkdocs 1.6.0
    - mkdocs-material 9.5.33

## 準備
1. （前提）pythonはインストール済みとする。
1. [MkDocsをインストールする](https://www.mkdocs.org/user-guide/installation/)
    ```sh
    pip install mkdocs
    ```
1. [mkdocs-materialをインストールする](https://squidfunk.github.io/mkdocs-material/getting-started/)
    ```sh
    pip install mkdocs-material
    ```

## 手順
1. mkdocsで新規プロジェクトを作成する。プロジェクト名はここでは`sample_project`とする。以下のコマンドを打つと，カレントディレクトリ配下に`sample_project`というフォルダができる。
    ```sh
    mkdocs new sample_project
    ```
1. `sample_project/docs/mkdocs.yml`ファイルを以下のように編集する。
    ```yml:mkdocs.yml
    site_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
    ```
1. `sample_project/docs/index.md`ファイルにmatlabコードを記載する。
    1. コードブロック` ``` `の後に`matlab`を追加して，言語を指定する
    1. インラインコードの場合は`:::matlab`か`#!matlab`を先頭につける
    1. コード行数をつける場合は，`{.matlab linenums=1}`とする。`linumes=2`とすると，先頭行が2から始まる。
    1. ファイル名をつける場合は,`{.matlab title="sample.m"}`とする。
    1. ほかのオプションは[mkdocs-material](https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#usage)のリファレンスを参照。
    1. 以下は冒頭の画像を作った時のサンプル。（プログラムは[mathworksのヘルプ](https://jp.mathworks.com/help/matlab/learn_matlab/scripts.html)から引用）
    ~~~: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;`
    ~~~
1. プロジェクトフォルダに移動し，`mkdocs serve`を行う。
    ```sh
    cd sample_project
    mkdocs serve
    ```
1. http://127.0.0.1:8000/ を開くと以下の画像（冒頭の画像）が表示される。コメントが灰色になっていたり，関数が紫色になっていることがわかる。デフォルト（全部黒）よりは見やすくなっている。![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/260124/86a7a27c-5b4a-bd5c-884e-78e48f453a35.png)

## 補足
1. 色が気に入らない場合は[ここ](https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#custom-syntax-theme)を参考にすれば変更できる。
1. matlabセッションのシンタックスハイライトをしたい場合は，`matlab`の代わりに`matlabsession`を指定すると見た目が少し良くなる（[参考](https://pygments.org/docs/lexers/#pygments.lexers.matlab.MatlabSessionLexer)）

## 参考
- https://squidfunk.github.io/mkdocs-material/reference/code-blocks/
- https://facelessuser.github.io/pymdown-extensions/extensions/highlight/