🙆

Marpで資料を管理するために導入したこと

2023/12/24に公開

Markdown

slide

Marp

tech

はじめに

とあるチームで学習コンテンツの作成を担当しているのですが、Google スライドから Marp に移行しました。
その際のナレッジなどをまとめておきます。

背景

IT エンジニアの学習コンテンツを作成する際に、Google スライドを使っていました。
しかし、作成はエンジニアが対応していたため、普段業務でも使うことがない Google スライドを用いてレビューするというのが非常に手間で、Git 管理したいという要望がありました。
結果として、Marp を導入することになりました。

Marp とは

Marp は Markdown でスライドを作成できるツールです。

https://marp.app/

Markdown はテキストベースで書けるため、Git 管理がしやすく、また、用意に HTML を生成できるため、癖はありますがエンジニアには馴染みやすいと考えました。

メリットとデメリット

Marp を既存のスライドツールと比較した場合のメリットとデメリットをまとめます。

メリット	デメリット
Git 管理ができるエンジニアに馴染みがある執筆環境（VS Code）	主に LT などを想定したツールで、レイアウトの柔軟性はない細かいスタイルを求めるなら自作テーマ必須

実際に導入したこと

1）テーマのカスタマイズ

Marp はデフォルトでいくつかのテーマが用意されていますが、今回は Google スライドのデザインは踏襲したかったので、自分でカスタムテーマを作成しました。
このナレッジは過去に所属会社のブログに書いていますので、そちらを参照ください。

これによって背景や中表紙、段落やリストなどを Google スライドに近づけることができました。
さらにカスタムテーマの中でよく使うスタイルを CSS クラスとして定義しました。

2）Bootstrap の導入

Marp はデフォルトで画像の配置、サイズなどが定義されていますが、それでもスライドツールと比較すると機能的には不足です。
具体的には画像幅をパーセンテージで指定できない、自由に N カラム構造でレイアウトが作れない、などです。
そこで今回のカスタムテーマには Bootstrap を導入しました。

Bootstrap は CSS フレームワークで、レスポンシブデザインやグリッドシステムなどが用意されています。

3）差し込み画像を Draw.io に統一

Marp は画像を差し込む際に画像ファイルの Path を指定するか、URL を指定するかの 2 通りの方法があります。
しかし本プロジェクトで紹介する画像はほとんどがロジック図などであり、画像ファイルとして管理するのは不適切でした。
そこで VS Code の拡張機能経由で Draw.io を利用することにしました。
拡張子を.drawio.svgにすることで、VS Code 上では.svgとして扱われるので、画像としてエクスポートする手順が省略され、効率が上がりました。

4）VS Code のカスタマイズ

Marp は VS Code の拡張機能として提供されています。
ここまでに導入した内容を適用するために、VS Code の設定をカスタマイズしました。
具体的には以下の項目を設定しました。

テーマをカスタムテーマに変更
スニペットを追加

テーマをカスタムテーマに変更

VS Code の設定で、Marp のテーマをカスタムテーマに変更します。
これによって VS Code 上でカスタムテーマが適用されます。
さらにスニペット関連や、文章校閲の設定も導入しました。

VS Code の設定

.vscode/settings.json

{
  "markdown.marp.enableHtml": true,
  "markdown.marp.themes": ["./themes/my_theme.css"],
  "japanese-proofreading.textlint.丸かっこ（）": false,
  "japanese-proofreading.textlint.全角文字と半角文字の間": false,
  // スニペット設定、不要な人はコメント化推奨
  "[markdown]": {
    "editor.quickSuggestions": {
      "comments": "off",
      "strings": "off",
      "other": "on"
    },
    "editor.snippetSuggestions": "top",
    "editor.suggest.showKeywords": false,
    "editor.suggest.showWords": false
  }
}

スニペットを追加

以下の要素をすべてスニペットとして追加しました。

よく使うページ（表紙、中表紙、最終ページ）
Markdown 記法だけでは難しいが、スライドとして欠かせない要素（朱書き、画像幅指定、カラムレイアウト）

カスタム CSS やページの差し込み方はさすがに暗記できないので、スニペットとしてすぐに使えるようにしました。
スニペットの設定は以下のようになっており、1 つにスニペットに複数の呼び出しワードを設定したり、先頭を!に固定したり、工夫しています。

スニペットの設定

markdown.code-snippets

{
  "text-red": {
    "prefix": ["!red"],
    "body": "<span style='color:red'>${TM_SELECTED_TEXT}</span>",
    "description": "選択部分を赤文字のスタイル適用"
  },
  "slide-middle": {
    "prefix": ["!middle"],
    "body": [
      "---",
      "",
      "<!-- _class: middle -->",
      "",
      "## タイトル",
      "",
      "![bg fit](../themes/img/middle_a.png)",
      "",
      "---"
    ],
    "description": "中表示のスライド"
  },
  "slide-init": {
    "prefix": ["!init", "!top", "!start"],
    "body": [
      "---",
      "title: My Slide",
      "theme: my_theme",
      "author: my_theme",
      "marp: true",
      "size: '16:9'",
      "paginate: true",
      "---",
      "<!-- _class: titlepage -->",
      "",
      "## タイトル",
      "",
      "![bg fit](./../themes/img/start.png)",
      "",
      "---",
      "",
      "## 目次",
      "",
      "- hoge",
      "- fuga",
      "",
      "---"
    ],
    "description": "スライド情報〜目次"
  },
  "slide-end": {
    "prefix": ["!end"],
    "body": [
      "---",
      "",
      "<!-- _class: endpage -->",
      "",
      "## お わ り",
      "",
      "![bg fit](./../themes/img/end.png)",
      ""
    ],
    "description": "おわりスライド"
  },
  "img-width": {
    "prefix": ["!img"],
    "body": ["<!-- _class: img-w80 -->"],
    "description": "画像幅指定クラス（パーセンテージ）"
  },
  "codeblock-float": {
    "prefix": ["!float-codeblock"],
    "body": ["<!-- _class: pre_float_l -->"],
    "description": "コードブロックのfloatクラス"
  },
  "img-float-right": {
    "prefix": ["!float-img"],
    "body": ["<!-- _class: img_float_r -->"],
    "description": "画像のfloatクラス"
  },
  "bubble": {
    "prefix": ["!bubble"],
    "body": ["<div class='bubble'>", "", "hogehoge", "", "</div>"],
    "description": "バブル"
  },
  "column-layout": {
    "prefix": ["!column"],
    "body": [
      "<div class='row'>",
      "  <div class='col-6'>",
      "",
      "![](./../themes/img/middle_b.png)",
      "",
      "  </div>",
      "  <div class='col-6'>",
      "",
      "![](./../themes/img/middle_d.png)",
      "",
      "  </div>",
      "</div>"
    ],
    "description": "2カラムレイアウト"
  }
}

導入してみて

これまで Google スライドですと、改修する、レビューするといったオペレーションがエンジニアにとっては非常に手間でした。
Marp に移行してからは Markdown で執筆してデータは GitHub 管理という運用にできましたので、レビューも GitHub 上で行えるようになり開発体験が上がりました。
大元のデザインもカスタムテーマを作成することで踏襲できたので、スライドの品質についても大きな問題は発生しませんでした。

さいごに

この仕組みを使っていたプロジェクトは Figma を導入することになり、今後 Marp は徐々に廃止する予定です。
しかし、Marp はエンジニアが文書を運用管理するにあたっては非常に使いやすいツールであると感じましたので、今後も個人的には選択肢に含めていきたいと思います。