【Marp】MarkdownをA4テキストにする方法

$Markdown$を「ちゃんと」$A4$にしよう

本記事では、$Markdown$で発表スライドを作るツールである$Marp$を用いて、$A4$スライドを作る方法について述べます。$A4$サイズのスライドがそのまま$A4$テキストとして使えるという算段です。

前置き：$Markdown$の特徴おさらい

$Markdown$とは便利なもので、｢簡単な記法で整ったテキストを作成できる｣点で非常に優れています。

$Markdown$の良い所

$Markdown$よりも整ったテキストを作る手段は数多あります。最も有名なのは、$Microsoft$の$Word$でしょう。また、マークアップ言語である$HTML$も、$Web$開発を主として世界的に普及し、利用されています。

しかし、$Word$には専用のアプリケーションが必要な他、バージョンや環境の違いによって、表示が崩れることがあります。一方$HTML$は然程環境に左右されないものの、記述が複雑になりがちです。

HTMLで書く表の例

<table>
  <thead>
    <tr>
      <th>用紙サイズ</th>
      <th>寸法 (幅 × 高さ / mm)</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>A0</td>
      <td>841 × 1189</td>
    </tr>
    <tr>
      <td>A1</td>
      <td>594 × 841</td>
    </tr>
    <tr>
      <td>A2</td>
      <td>420 × 594</td>
    </tr>
    <tr>
      <td>A3</td>
      <td>297 × 420</td>
    </tr>
    <tr>
      <td>A4</td>
      <td >210 × 297</td>
    </tr>
  </tbody>
</table>

上の$HTML$をブラウザーで表示すると、あまりにも簡素過ぎる表が出来上がります。

---

その点$Markdown$は、メモ帳などでテキストファイルを作成するだけです。記述も簡単です。表を書く際に、この違いは顕著になります。

Markdownで書く表の例

|用紙サイズ|寸法 (幅 × 高さ / mm)|
|:-|:-|
|A0|841 × 1189|
|A1|594 × 841|
|A2|420 × 594|
|A3|297 × 420|
|A4|210 × 297|

上のテキストは下のように表示されます。

用紙サイズ	寸法 (幅 × 高さ / mm)
A0	841 × 1189
A1	594 × 841
A2	420 × 594
A3	297 × 420
A4	210 × 297

メモ帳で表示した場合
左上のはみ出た線のようなものはカーソル

$Markdown$の弱点

環境に左右されづらく記述も簡単という、良いとこどりのような$Markdown$ですが、書籍で言うページという概念がありません。$Word$には辛うじて改ページ機能がありますが、$Markdown$にそのようなものはありません。

つまり、$Markdown$だけでは本当の意味での$A4$テキストは作れないと、そう言えるのではないでしょうか。

明確なページの区切りがありませんから、思いがけぬことが原因でページが崩壊するおそれがあります。そうなっては、テキストとして粗悪だと評されてしまうこともあるでしょう。

表がたった一行のみページを跨いでいる

個人のレベルであれば、特段気にならないという方もあるでしょう。しかし仕事で人に見せられたテキストがこの出来栄えだったならどうでしょう、粗雑さを感じてしまうのではないでしょうか。

始めから$Markdown$なんて使わなければ良かったのに

折角工夫したところに斯くも辛辣な言葉は、言いたくも、言われたくもないでしょう。

本題：$Marp$で$A4$ページを作る

$Marp$は、$Markdown$の記法を応用して発表スライドを作るものです。要は、$PowerPoint$のようなものです。

スライドを作るものですから、スライド一枚一枚が完全に別のページになります。つまり、$Markdown$には無かった、ページの概念を導入できるのです。

通常は$A4$ではない

発表スライドが$A4$で作られることはほぼないように、$Marp$で作られるスライドもまた$A4$ではありません。

$A4$にするには

$Markdown$同様、$Marp$には$CSS$を適用することができます。つまり、$CSS$でスライドの縦横比を$A4$にすれば、$A4$スライドができあがります。しかし$Marp$に$CSS$を適用するには、少々設定が必要です。

$\huge{\frak{1}}.$ $Marp$ $for$ $VSCode$の場合

$Marp$と言えば、$VSCode$の拡張機能である「$Marp$ $for$ $VSCode$」を使っている方も多いのではないでしょうか。以前投稿した下の記事ですが、私のものにしては珍しく$2000$回以上表示されているとのことで、或る程度の関心があるのだと感じています。

https://zenn.dev/link/articles/3aafed215725e9

本記事では、$VSCode$のインストール手順は省略します。

$\tt{1}.$ $Marp$の設定を開く

$Marp$のアイコン→Open Extension Settingsを選択すると、$Marp$の設定が開かれます。

$\tt{2}.$ テーマを設定する

Markdown › Marp: Themesという項目がありますので、ここにテーマとなる$CSS$ファイルの所在を記します。

$CSS$ファイルは自分で作成するところですが、$GitHub$にて公開されているファイルがありますので、先ずはそちらを紹介します。

https://github.com/pn11/marp-A4-theme

このREADME.mdによれば、https://raw.githubusercontent.com/pn11/marp-A4-theme/main/themes/A4.cssというリンクをMarkdown › Marp: Themesに設定すれば良いとのことです。「項目の追加」に$URL$を貼付してOKすれば、下のようになります。

$\tt{3}.$ テーマを使用する

先のREADME.mdを見ると、設定後は$Marp$側でこのように記載せよとあります。

抜粋：<https://github.com/pn11/marp-A4-theme>

---
marp: true
theme: A4
---

このA4というのは、テーマの名前です。A4.cssというファイル名と一致していますが、厳密には、ファイル名とテーマ名とは関係ありません。

これでテーマが適用され、スライドが$A4$サイズになります。

しかし、確かに$A4$にはなったものの、これを見ると表題が不適当に改行されていたり、左右の余白がやや大きすぎたりと、細かな箇所を調整しなければならないように見えます。

$\tt{4}.$ カスタムテーマを作成する

今使用したのは既製の$CSS$ファイルでしたから、作成するテキストに応じた$CSS$ファイルを作ってみましょう。

自分で書く前に、先ほど使用した$CSS$の内容を見てみます。

https://github.com/pn11/marp-A4-theme/blob/main/themes/A4.css

---

第一に目に入るのは、このコメントです。

/* @theme A4 */

一見して唯のコメントですが、$Marpit$($Marp$で発表スライドを生成している張本人)のドキュメントによれば、これは「$Metadata$」というものであり、省略してはならないそうです。このメタデータに記載した名称が、先述のテーマ名となります。

https://marpit.marp.app/theme-css?id=metadata

メタデータの次に@import 'default';と記載して、$Marp$標準のテーマを読み込んで踏襲しています。これにより、この後に記述する内容は、標準のテーマを上書きすることになります。

---

A4の寸法

section {
  width: 210mm;
  height: 297mm;
}

sectionに縦横の大きさを記載することで、スライドの大きさを変更することができます。$A4$の寸法である「横 $210$ ㎜、縦 $297$ ㎜ 」に設定することで、スライドが$A4$になっているのです。

後のh2やh3などは見出し、pは段落、liはリストについて定義しています。これらの記述を適宜変更・追加すれば、作成する内容に合ったデザインになります。

取り敢えず、表題が収まる程度に$CSS$を記述しました。

CustomA4.css

/* @theme CustomA4 */

@import 'default';

section {
  width: 210mm;
  height: 297mm;
  padding: 40px; /* 余白の調整 */
}

h1 {
    font-size: 35px;
}

p {
    font-size: 22px;
}

$\tt{5}.$ カスタムテーマを適用する

先ほど設定のMarkdown › Marp: Themesに$URL$を記載したのと同様に、$CSS$ファイルの所在を記載すれば、テーマとして使用できるようになります。

⋯そのはずなのですが、ユーザー単位の設定に絶対パスで記載したところ、適用されませんでした。そこで、ワークスペース単位での設定に記載します。

「ユーザー」ではなく「ワークスペース」で設定するため、相対パス

ワークスペース単位での設定が有効になると、.vscodeという隠しフォルダーと共に、設定ファイルが作成されます。この設定内容は、他のフォルダーを開いている際には適用されません。

これで、カスタムテーマが適用されました。表題が一行に収まり、左右の余白が小さくなりました。右の余白が大きく見えますが、句点の影響で改行されているためで、本来の領域は確り左右均等になっています。

段落の方は一文毎に改行してある

$\tt{6}.$ スライドに変換する

スライドへの変換に特別なことは必要ありません。通常の$16:9$スライドの場合と同じ手順で変換することができます。設定を開いた時のように、下のコマンドパレットを表示します。但し今回は、Export Slide Deckとあるのを選択します。

Export Slide Deckを選択する

標準の設定では、この操作で$PDF$へと変換されるようになっています。

$PDF$へ変換する処理には$Web$ブラウザーが使われます。そのため、$Marp$ $for$ $VSCode$がブラウザーを探せなければなりません。探せず変換に失敗した場合の対処はこちら。

$PDF$以外にも$HTML$や$PNG$など、複数のファイル型式に変換することができます。変換型式は設定から変更できます。

Export Typeを変更する

註書きしたように、$PDF$への変換には失敗することがあるため、まずは$HTML$に変換するのが無難でしょう。

発表者ツールも使える(右)

$Marp$には$Marpit$という仕組みが備わっているため、$Markdown$を発表スライドという別物に変換できているのです。この$Marpit$の持つ大きな特徴として、$HTML$に変換しても単なるファイルになるのではなく、「発表機能を備えた$HTML$ファイルが出来上がる」点が挙げられるでしょう。$PowerPoint$のような発表者ツールも使えるので、その気があれば$A4$テキストをそのままプレゼンテーションで使用することもできるのです。うれしいですね。

$\huge{\frak{2}}.$ $Marp$ $CLI$の場合（ややエンジニア向）

https://github.com/marp-team/marp-cli

$Marp$ $CLI$を導入すれば、コマンドmarpを使うことができます。sample.mdというファイルがあるならば、次のコマンドで$HTML$に変換されます。わざわざ設定を開いて、変換型式を$PDF$から$HTML$に変更するような手間はありません。

convert to HTML

marp --html sample.md

コマンドで変換できるということは、「$AI$エージェントにスライドの作成から変換までを任せることができ、自動化できる」ということです。$AI$に一任したいなら、$VSCode$ではなくこちらの$Marp$ $CLI$を使うとよいでしょう。

なお、$Marp$や$CSS$ファイルの記述に関する内容は、$Marp$ $for$ $VSCode$の項にて既に述べたものとして、本項では省略します。

$\tt{0}.$ $Node.js$が使える環境を用意する

ドキュメントによれば、$Mac$や$Linux$であればbrew、$Windows$ならばscoopでもインストールできるそうですが、本記事では取り挙げません。

端から主題を離れるような手順が入ります。$Marp$ $CLI$を使う方法がエンジニア向というのは、大方このためです。

$Node.js$の名を聞いたことがないという方は、先ずは「自分の$PC$にはインストールしない」ことをお薦めします。理由は単に、不要だからです。本来は$Web$サーバーでの開発に使う業務用のものですから、非エンジニアの個人が使う機会は必ずしも多くありません。

自分の$PC$に$Node.js$をインストールするのは、$Marp$ $CLI$を大いに気に入ったとか、他の用途を幾つも確立したとか、ないと困るくらいになってからで充分でしょう。

エンジニアの諸賢であれば、既に$Node.js$などインストールしてあるとか、少し調べれば直ぐにインストールできるとか、さほど苦労する作業ではないはずです。しかし非エンジニアにとって、$Node.js$をインストールすることは案外難しいものだと思います。

詳しい手順は主旨から乖離するため述べませんが、本記事ではクラウドサービスや仮想環境を推奨します。

クラウドサービスではこれらが無料でお薦めです。

• $Google$ $Cloud$ $Shell$
  $Google$アカウントがあれば、直ぐに自分専用のクラウド環境が使えるようになります。この環境には、始めから$Node.js$が備わっています。
• $GitHub$ $Codespaces$
  $GitHub$アカウントを作る必要があったり、動作が遅かったりするものの、上と同様無料で手軽に使えるクラウド環境です。

環境を汚したくないエンジニアの方には、$Conda$や$Pixi$で仮想環境を作る方法がお薦めです。

Pixiを使った例

PS C:\⋯\A4> pixi init
Created C:\⋯\A4\pixi.toml
PS C:\⋯\A4> pixi add nodejs    
Added nodejs >=26.2.0,<26.3
PS C:\⋯\A4> pixi shell
(A4) PS C:\⋯\A4> npm -v
11.13.0

$\tt{1}.$ $Marp$ $CLI$をインストールする

https://github.com/marp-team/marp-cli#use-nodejs

$Node.js$には、$Node$ $Package$ $Manager$(npm)というものがあります。これによって$Marp$ $CLI$をインストールします。

local installation(推奨)

npm install --save-dev @marp-team/marp-cli

Pixiを使ったインストール例

(A4) PS C:\⋯\A4> npm install --save-dev @marp-team/marp-cli
npm warn deprecated mathjax-full@3.2.2: Version 4 replaces this package with the scoped package @mathjax/src

added 153 packages in 14s

19 packages are looking for funding
  run `npm fund` for details
npm notice
npm notice New minor version of npm available! 11.13.0 -> 11.15.0
npm notice Changelog: https://github.com/npm/cli/releases/tag/v11.15.0
npm notice To update run: npm install -g npm@11.15.0
npm notice

$Node$ $Package$ $Manager$でインストールしたものは、$Node$ $Package$ $eXecuter$(npx)で実行します。そのため、npx marpとしないとエラーになる点に注意しましょう。

バージョンを表示するコマンド

npx marp --version

Pixiを使った実行例

(A4) PS C:\⋯\A4> marp
marp: The term 'marp' is not recognized as a name of a cmdlet, function, script file, or executable program.
Check the spelling of the name, or if a path was included, verify that the path is correct and try again.
(A4) PS C:\⋯\A4> npx marp --version
@marp-team/marp-cli v4.4.0 (w/ @marp-team/marp-core v4.3.0)

単にmarpと入力した場合には、長いエラーメッセージが表示されています。それに対し、npx marpと入力した場合には、正しくコマンドとして認識され、バージョン情報が表示されています。

$\tt{2}.$ $CSS$ファイルを指定するには

$VSCode$同様、カスタムテーマを使うには$CSS$ファイルを指定する必要があります。$Marp$ $CLI$の場合、次のようにオプションを記載するだけでよく、設定を変更するような手間はありません。

sample.mdとcustom_theme.cssというファイル名だった場合、このようになります。

HTMLに変換する例(npxは省略)

marp --html sample.md --theme custom_theme.css

$\tt{3}.$ $HTML$に変換する

Pixiを使った変換例

(A4) PS C:\⋯\A4> npx marp --html .\HowToMakeSlideA4.md --theme .\CustomA4.css   
[  INFO ] Converting 1 markdown...
[  INFO ] HowToMakeSlideA4.md => HowToMakeSlideA4.html

以上が$Marp$ $CLI$による主な手順です。

$\tt{Q}.$ $inline$ $CSS$ではだめなのか

$Marp$に限らず$Markdown$ファイルでは、$CSS$を直接記述することもできます。特に$Marp$では、インライン$CSS$と言って次のような記述が可能です。

左右余白なし、フォント変更、フォントサイズ変更

画像の例

---
marp: true
style: |
    section {
        padding: 0px;
        font-size: 80px;
        font-family: "Georgia";
    }
---

# Marp × CSS

管理のしやすさという観点では、単一ファイルの中に$Marp$と$CSS$が混在しているのは、あまり好ましくありません。しかしもっと根本的な理由から、$CSS$ファイルに分離しています。

スライド自体は$A4$になっているが、それを表示できていない

私の環境では、いくら試しても上の画像のような状態になりました。
スライドには確かに$CSS$による変更が適用されており、$A4$になっています。しかしスライドを表示する枠は$16:9$のままで、スライドの下部が隠れてしまっています。それだけでなく、スライドの無い右側の空間が表示されたままになっています。この現象は、$HTML$等に変換してもそのままです。

このような理由から、$CSS$ファイルを別に用意して、カスタムテーマとして使用する必要があったのです。

$A4$にしてみて気になったこと

$Marp$の(テーマの)特徴として、文章などのコンテンツは全て上下方向に中央寄せになっています。

上下中央寄せになっている

この特徴は発表スライドとしては都合好いものでしたが、テキストとしては不格好に感じられます。しかし厳密には、この事象は$CSS$によって定義されたものなので、カスタムテーマの記述次第でどうにかできるのかもしれません。