export 関数でライブスクリプトから markdown 変換（R2023b 新機能）

これまで[【MATLAB】ライブスクリプトの Markdown 変換で楽して Qiita 投稿](https://qiita.com/eigs/items/513a17bd8cb2c5c5f435)で紹介している livescript2markdown 関数を使っていましたが、、


```matlab
export("doc.mlx","README.md",EmbedImages=false);
```

と、export 関数（[LINK](https://jp.mathworks.com/help/matlab/ref/export.html?lang=en)）がついに markdown (Jupyter® notebook も）への変換が公式サポートするようになりました（Doc は英語で表示しないと R2023b (最新版）の内容が表示されないので要注意です）


正確な仕様はドキュメントを確認するとしても、ちょっとややこしいので markdown 変換に絞って使い方例をまとめます。

-  使用環境：R2023b 

これを機に [export 関数](https://jp.mathworks.com/help/matlab/ref/export.html?lang=en)を使うようにしたいと思います。

コードは[GitHub:how2export](https://github.com/minoue-xx/livescript2markdown/blob/master/doc/how2export/README.md)にもおいています。


## 準備

doc.mlx を用意して export 関数で変換しながら挙動を確認する感じで進めます。doc.mlx に画像やら数式を入れておきます。

### 数式
 $$ \begin{array}{rl} \frac{\partial u}{\partial t}+u\cdot \nabla u & =-\nabla p+\frac{1}{Re}\nabla^2 u\\\\ \nabla \cdot u & =0 \end{array} $$ 
### 画像
```matlab
surf(peaks);
```

![figure_0.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/149511/88083c56-5340-df5b-99e0-428541d0789b.png)

# デフォルトの動作
```matlab
export("doc.mlx","doc_ver1.md");
```

結果はこちら：[doc_ver1.md](https://raw.githubusercontent.com/minoue-xx/livescript2markdown/master/doc/how2export/doc_ver1.md) 


ファイルを見ると数式は

<pre> $$ \begin{array}{rl} \frac{\partial u}{\partial t}+u\cdot \nabla u & =-\nabla p+\frac{1}{Re}\nabla^2 u\\ \nabla \cdot u & =0 \end{array} $$ 
</pre>

そして画像は

![image_0.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/149511/8994557e-c417-0e9d-f772-c14191797cd6.png)

こんな感じ。画像が埋め込まれちゃってますね。画像等のファイルを出さずに markdown ファイル１つで済む点はメリットですが、画像ファイルも欲しい（個別に確認したい）場合は不便ですね。


ちなみに、

<pre>export("myscript.mlx",Format="markdown")
</pre>

livescript 名と同じ markdown ファイルですとこんな実行方法でもOK.

# 画像ファイルも作る場合

画像ファイルを別途作成させる場合はこれ。`EmbedImages` オプションを設定します。

```matlab
export("doc.mlx","doc_ver2.md",EmbedImages=false);
```

結果はこちら：[doc_ver2.md](https://raw.githubusercontent.com/minoue-xx/livescript2markdown/master/doc/how2export/doc_ver2.md) 


今度は

![image_1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/149511/ad2f1d57-a116-0d76-4557-b65e2ddac014.png)

と、画像ファイルを参照しています。


画像ファイルは (markdown ファイル名)_media のフォルダ内に保存されますね。今回のケースですと [<samp>doc_ver2_media</samp>](doc_ver2_media) です。


ちなみに画像ファイル形式は FigureFormat から選べますが、<samp>Run</samp> オプションを <samp>true</samp> にし markdown 変換前に一度 livescript を実行させるようにしないといけない点に要注意。

<pre>export("doc.mlx","doc.md",EmbedImages=false, FigureFormat='jpeg', Run=true);
</pre>

選べる選択肢は以下の通り


**<samp>FigureFormat</samp>** **—** **Figure format**


<samp>"png"</samp> | <samp>"jpeg"</samp> | <samp>"bmp"</samp> | <samp>"svg"</samp> | <samp>"eps"</samp> | <samp>"pdf"</samp>

# 数式は画像で表示したい場合

少し前まで GitHub がそうでしたが、 latex がレンダリングされない環境だと数式は画像にして表示しましょう。<samp>RenderLaTeXOnline</samp> オプションです。<samp>"svg"</samp> | <samp>"png"</samp> | <samp>"jpeg"</samp> から選べますが、ここでは <samp>"svg"</samp> で行ってみます。

```matlab
export("doc.mlx","doc_ver3.md",RenderLaTeXOnline='svg');
```

結果はこちら：[doc_ver3.md](https://raw.githubusercontent.com/minoue-xx/livescript2markdown/master/doc/how2export/doc_ver3.md) 


数式部分は

![image_2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/149511/08670d39-c3be-0f51-b6c8-05299ec42134.png)


こんな感じで latex.codecogs.com のサービスを利用しています。


便利なのですがダークモードで表示すると見えない、見にくいなどの課題がある点は要注意です。

# その他使うかもしれないオプション
### **<samp>IncludeOutputs</samp>** **—** <samp>true</samp> or <samp>1</samp> (default) | <samp>false</samp> or <samp>0</samp>

コードの出力結果を含めるかどうか。デフォルトでは <samp>true</samp> になってます。

### **<samp>Run</samp>** **—** <samp>false</samp> or <samp>0</samp> (default) | <samp>true</samp> or <samp>1</samp>

変換前に一度コードを実行するかどうか。デフォルトでは false になってます。まだ実行していない livescript で出力が欲しい場合は実行した方がいいですね。

### **<samp>HideCode</samp>**  **—** <samp>true</samp> or <samp>1</samp> | <samp>false</samp> or <samp>0</samp>

コードを隠しての出力。基本的に livescript 側の設定（表示・非表示）に従いますが、このオプションで指定可能。

### **<samp>AcceptHTML</samp>** **—** <samp>true</samp> or <samp>1</samp> (default) | <samp>false</samp> or <samp>0</samp>

細かい色の設定（タイトル）や挿入した画像のサイズなどしっかり markdown にも反映させたい場合に必要。ただ表示側の環境に依存します。

### **<samp>FigureResolution</samp>** **—** <samp>600</samp> (default) | positive integer

画像の解像度設定ですね。

# まとめ

以上！基本的なところだけですが簡単に紹介いたしました。


```matlab
export("doc.mlx","README.md",EmbedImages=false);
```

でこの投稿の markdown としました。


[【MATLAB】ライブスクリプトの Markdown 変換で楽して Qiita 投稿](https://qiita.com/eigs/items/513a17bd8cb2c5c5f435) で紹介した関数・コードが製品に（開発チームの大幅な修正・慎重な検証ののち）採用されたということで思い入れの強い関数 [export](https://jp.mathworks.com/help/matlab/ref/export.html?lang=en) のご紹介でした。