markdown-slides

Markdown スライドスキル

Deckset および Marp のプレゼンテーションツールに対応した Markdown 形式のスライドに、コンテンツを変換します。

このスキルを使用する場合

次のような依頼があった場合に、このスキルを有効にします。

• スライドやプレゼンテーションの作成を依頼された
• ドキュメントをスライド形式に変換するよう依頼された
• Deckset または Marp について言及された
• 発表者ノートの生成を希望された
• プレゼンテーション用の画像の書式設定が必要とされた

入力要件

• ソースコンテンツ：Markdown ファイル、アウトライン、または構造化されたコンテンツ
• 画像：_files_/ ディレクトリ内のファイル、または解決が必要なパス
• 対象プラットフォーム：Deckset（デフォルト）または Marp
• オプション：
  • 発表者ノート（デフォルトで有効）
  • スライド番号（オプションのフロントマター）
  • 絵文字の追加（デフォルトで有効）

出力仕様

• ファイルの場所：ソースと同じフォルダー
• ファイル名：元の名前に - slides の接尾辞を追加
  • 例：document.md → document - slides.md
• 形式：Deckset 互換の Markdown
• 構造：適切なスライド区切り、画像タグ、発表者ノート
• 仕上げ：視覚的な訴求力を高める絵文字を追加

主なプロセス

ステップ 1：スライド構造の設定

目的：適切な階層で論理的にスライドを区切ります

作業：

1. ソースコンテンツの構造を読み取り、分析します
2. 論理的な区切りにスライド区切り（---）を挿入します。
   • 大きなセクションの間
   • 内容の異なるトピックの間
   • セクションの導入スライドの後
   • 大きな図の前後
3. コンテンツの階層を維持します。
   • セクションタイトルには H1（#）
   • メインのスライドタイトルには H2（##）
   • サブトピックには H3（###）
4. 元の構成と流れを維持します
5. オプションでフロントマターを追加します：slidenumbers: true

例：

slidenumbers: true
# 1. Section Title 🎯

![](section-background.png)

^ Introduction to this section.

---

## Main Topic 📊

Content here...

---

### Detailed Subtopic

More details...

ステップ 2：画像形式の変換

目的：適切な配置で画像を Deckset 形式に変換します

重要な要件： ⚠️ 画像ごとに相対パスを必ず解決してください ⚠️ スペースを必ず URL エンコードし、特殊文字をエスケープしてください ⚠️ 画像ファイルの存在を必ず確認してください

画像の配置形式：

形式	用途	例
![]()	セクション導入の背景	
![inline]()	テキストの流れの中に図を配置	
![right fit]()	主に使用：コンテンツスライド	
![right 80%]()	特定のサイズが必要な場合	
![inline fill]()	インラインで全幅表示	

作業：

1. ソース内の画像参照をすべて特定します
2. 画像ごとに次を行います。

   a. Determine appropriate position format
   b. Resolve relative path from slide file location
   c. URL-encode spaces: " " → "%20"
   d. Escape parentheses: "(" → "%28", ")" → "%29"
   e. Verify file exists at resolved path
   f. Use original images when available
   g. Copy missing images to _files_/ directory
   

3. コンテキストに応じて配置を適用します。
   • セクション導入：背景全体に ![]() を使用
   • テキスト内の図：![inline]() を使用
   • コンテンツスライドのデフォルト：![right fit]() を使用 ⭐
   • サイズのカスタマイズ：必要に応じて ![right XX%]() を使用
   • インラインで全幅表示：幅広の画像には ![inline fill]() を使用

例：

# Section Title
![](background-image.png)

---

## Content Slide
Key points here:
- Point 1
- Point 2

![right fit](diagram.png)

---

## Inline Diagram
Text before diagram.

![inline](process-flow.svg)

Text after diagram.

ステップ 3：発表者ノートへの変換

目的：適切なコンテンツを発表者ノートに変換します

形式：^ （キャレットとスペース）で始まる行

配置：各スライドの末尾

発表者ノートに変換するもの： ✅ 複数の文からなる段落 ✅ 説明文 ✅ 追加の背景情報 ✅ 発表時の要点

変換しないもの： ❌ 1 文のみの段落 ❌ リスト（箇条書きまたは番号付き） ❌ 引用ブロック ❌ コロン（:）で終わる文 ❌ 見出し（H1、H2、H3） ❌ 表の内容

Marp プラットフォームの場合：代わりに HTML コメントを使用します

例：

## Slide Title

Main content visible to audience.

^ This paragraph becomes a speaker note because it's multi-sentence explanatory text. It provides context that the speaker needs but the audience doesn't need to read on the slide.

---

## Another Slide

- Bullet points stay visible
- Not converted to notes

^ Additional speaking points go here.

ステップ 4：コンテンツの強化

目的：最大限の効果が得られるよう、見せ方を洗練させます。

作業：

1. セクションとスライドのタイトルに絵文字を追加します。

   • 意味を補強する、適切な絵文字を使います。
   • 使いすぎず、プロフェッショナルな印象を保ちます。
   • 例：🎯📊🤖💡🚀📚🔧⚡

2. コメントを整理します。

   • スライドに不要な Markdown コメントを削除します。
   • TODO 項目を削除します。
   • 内部メモを削除します。

3. 書式を整えます。

   • 間隔を統一します。
   • 見出しの階層を適切にします。
   • スライドの区切りを明確にします。

4. フロントマターを追加します（指定がある場合）。

   slidenumbers: true
   

5. 最終確認を行います。

   • 各スライドの焦点が明確であること
   • 画像が適切な位置に配置されていること
   • スピーカーノートが末尾に配置されていること
   • 孤立したコンテンツがないこと

重要なガイドライン

画像の取り扱い

⚠️ 重要なルール：

1. 画像を絶対に捏造しないでください。ソースドキュメントまたは _files_/ フォルダーに存在する画像のみを参照します。存在しない画像に対して、background-xxx.png のようなプレースホルダーの参照を作成しないでください。
2. ソースに画像がある場合は、元の画像を使用します。
3. 不足している画像を差し替えるのではなく、_files_/ ディレクトリにコピーします。
4. パスは画像ごとに解決します。同じディレクトリにあると想定しないでください。
5. スペースを URL エンコードします：my file.png → my%20file.png
6. 特殊文字をエスケープします。
   • 括弧：( → %28、) → %29
   • その他の特殊文字も必要に応じてエスケープします。
7. 参照する前に、ls または glob を実行してファイルの存在を確認します。
8. 意味的な関連性を保ちます。画像はスライドの内容に合致している必要があります。
9. セクションの導入スライドに画像がなくても問題ありません。背景画像がない場合は、画像を参照せず、タイトルとスピーカーノートのみを使用します。

画像の配置基準

画像配置の判断フロー：

Is it a section intro slide with just title?
  → Does a background image exist?
    → YES: Use ![]() for full background
    → NO: Skip image, use title + speaker notes only

Is it a diagram embedded in flowing text?
  → YES: Use ![inline]() or ![inline fill]()

Is it the main visual for the slide with bullet points?
  → YES: Use ![right fit]() ⭐ PRIMARY FORMAT

Does it need specific sizing?
  → YES: Use ![right 80%]() or other percentage

スピーカーノートのルール

スピーカーノートにするもの：

• 複数文からなる説明的な段落
• スライドに不要な背景情報
• 発表者用の要点
• 口頭で説明するための補足情報

スピーカーノートにしないもの：

• 1 文だけの段落（スライドの内容である可能性があります）
• 箇条書きまたは番号付きリスト（通常はスライドの内容です）
• 引用（通常は目立たせるコンテンツです）
• : で終わる文（通常はリストの導入です）
• すべての見出しレベル
• 表の内容

形式：

Slide content here.

^ Speaker note paragraph one. Can be multiple sentences providing context.

^ Speaker note paragraph two. Each note paragraph gets its own ^ prefix.

コンテンツの基準

1. ファイル名：

   • 常に - slides の接尾辞を使用します。
   • それ以外は元のファイル名を維持します。
   • 例：AI for PKM.md → AI for PKM - slides.md

2. 絵文字の使用：

   • H1 および H2 の見出しに追加します。
   • 内容に合った、プロフェッショナルな絵文字を選びます。
   • 使いすぎず、量より質を重視します。
   • 例：
     • 🎯 目標／目的
     • 📊 データ／グラフ
     • 🤖 AI／テクノロジー
     • 💡 アイデア／洞察
     • 🚀 未来／ローンチ
     • 📚 学習／知識

3. 階層：

   • 主要なセクションには H1 を使用します（通常は番号付き）。
   • メインのスライドタイトルには H2 を使用します。
   • スライド内のサブトピックには H3 を使用します。
   • 一貫した番号体系にします。

4. スライドの区切り：

   • 独立した行に ---（ハイフン 3 つ）を使用します。
   • 前後に空行を入れることを推奨します。
   • トピック間を論理的に区切ります。

プラットフォーム固有の注意事項

Deckset（デフォルト）

形式：

• スピーカーノート：各行に ^ の接頭辞を付けます。
• 画像の配置：すべての形式に完全対応しています。
• フロントマター：シンプルなキーと値のペアです。

機能：

• slidenumbers: true によるスライド番号の自動付与
• 画像配置の完全な制御
• プレゼンターノートの充実したサポート

フロントマターの例：

slidenumbers: true
autoscale: true
theme: Plain Jane, 3

Marp（オプション）

形式：

• スピーカーノート：HTML コメント ``
• 画像の配置：異なる構文を使用する場合があります。
• フロントマター：marp: true を指定した YAML

Marp への変換：

---
marp: true
paginate: true
---

相違点：

• ^ 接頭辞の代わりに HTML コメントを使用します。
• フロントマターの構造が異なります。
• 背景画像には ![]() の代わりに ![bg]() が必要な場合があります。

品質チェックリスト

タスクを完了とする前に、以下を確認してください。

• 画像をでっち上げていない - すべての画像参照が実在するファイルを指している
• すべての画像に有効な URL エンコード済みパスが指定されている
• 画像ファイルが指定された場所に存在する（ls を実行して確認）
• パス内のスペースが %20 に変換されている
• 特殊文字が適切にエスケープされている
• スピーカーノートに ^ 接頭辞（または Marp 用の HTML）が使用されている
• スピーカーノートが各スライドの末尾に配置されている
• スライド区切り（---）が論理的な区切りに配置されている
• 見出し階層（H1 → H2 → H3）が一貫している
• タイトルに適切な絵文字が追加されている
• ファイル名に「- slides」接尾辞が付いている
• コンテンツの階層が原文から維持されている
• 孤立したコンテンツや壊れたセクションがない
• 内部コメントが削除されている
• 指示があれば Frontmatter が追加されている

エラー処理

画像が見つからない場合

問題：原文が存在しない画像を参照している

解決策：

1. ソースの _files_/ ディレクトリを確認します
2. 親ディレクトリの _files_/ を確認します
3. プロジェクト内で画像を名前で検索します
4. 見つかった場合：プレゼンテーションの _files_/ ディレクトリにコピーします
5. 見つからない場合：スピーカーノートに記載し、画像を省略します

相対パスが壊れている場合

問題：パスが正しく解決されない

解決策：

1. スライドファイルの場所を特定します
2. スライドから画像までの相対パスを計算します
3. パスが解決できることをテストします
4. 動作するパスを URL エンコードします

パスに無効な文字が含まれている場合

問題：特殊文字によって画像リンクが壊れる

解決策：

• スペース：%20 に変換します
• 丸括弧：( → %28、) → %29
• 角括弧：[ → %5B、] → %5D
• その他の特殊文字：URL エンコードを使用します

より良い結果を得るためのヒント

1. アウトラインから始める：まず、セクションとスライドの構成を明確にします
2. 1 スライドにつき 1 つのアイデア：各スライドに、明確なメッセージを 1 つだけ含めます
3. 視覚的な階層：セクションには H1、スライドには H2、補足項目には H3 を使用します
4. 画像の配置：コンテンツスライドでは、既定で ![right fit]() を使用します
5. スピーカーノート：スライドが煩雑になることなく、発表者の助けとなる背景情報を追加します
6. 絵文字の一貫性：類似する概念には類似の絵文字を使用します
7. Deckset でテストする：スライドをプレビューして、書式を確認します
8. 反復する：1 回目は構成、2 回目は仕上げに重点を置きます