--- title: "Markdownの表示と構造化ブロック" description: "通常Markdown、Mermaid、コード、Media、WikiLink、mindmap・brainstormの構文と表示。chat・共有文書・公開ガイド・共有Markdownの違い、読取専用操作、エラーからの復旧を説明する。" --- # Markdownの表示と構造化ブロック aachatのMarkdownには、Mermaidに加えて2つの構造化fenced blockがある。**mindmap**（思考の整理）、**brainstorm**（案の発散）である。chatメッセージにも共有ドキュメント本文にも書け、WebUIがインタラクティブなカードとして描画する。 2つに共通する事実: - **表示は読み取り専用**である。折りたたみ・並べ替え・コピーはできるが、UIから内容（rating等）を変更する操作はない。更新はMarkdown本文の編集で行う - ブロックを書いても**何も自動実行されない** - 構文エラーがあるとブロック全体がエラー表示（行番号付き）になり、元のテキストがそのまま表示される - どれも思考・調整のための作業面であり、正本ではない。固まった結論は通常の文書・依頼文に圧縮する ## 書く前に — 表示と実行を分ける 文章、表、図、成果物への参照を同じ本文にまとめ、読者が内容を確認できるようにするためのガイドである。chatへ投稿できる人・agent、または対象の共有ドキュメントを編集できる人・agentがMarkdownを書く。閲覧できることと、本文を変更できることは別の権限である。文書の保存・編集条件は[共有ドキュメント](/ja/docs/shared-documents)、媒体の準備は[Project Media](/ja/docs/media)を参照する。 **コード、Mermaid、構造化ブロックを表示しても、その内容をコマンドとして実行せず、Sessionの起動や担当agentへの委任も行わない。** `[Agent]` は担当の記述であり、権限の付与ではない。チェックボックス、rating、statusは本文に書いた値の表示である。実行する仕事は別途[Sessionへの依頼](/ja/docs/sessions)として渡す。 ただし、表示には図の描画や認証済みMediaの取得が伴う。リンクを開く操作も外部へのアクセスになりうる。「自動実行しない」は通信が一切ないという意味ではない。生のHTMLを貼っても、このMarkdown表示面で任意のHTML・scriptを実行する用途にはならない。HTML成果物は別の[Project HTML](/ja/docs/html)の実行・共有条件に従う。 ## 表示と読取専用操作の対応表 ここでのchatはWebUIのメッセージ本文、共有文書はWebUIのMarkdownプレビューを指す。下の2ブロックの例では、外側の4個のバッククォートはガイドで構文を見せるための囲いである。利用時には内側の3個のバッククォートから閉じる3個までを本文へコピーする。例中の数値・計画は説明用であり、測定結果ではない。 | 構文 | chat・共有文書での表示と閲覧操作 | エラー・制限と直し方 | |---|---|---| | 通常Markdown | 見出し、強調、引用、箇条書き、表、リンク、取消線、タスクリスト。リンクを開き、幅広の表を横スクロールできる | チェック状態はクリックで保存されない。`- [ ]` / `- [x]` を本文で編集する。表には区切り行を付ける | | 通常のcode fence | 言語名付きコード表示とコピー。コードを実行するボタンではない | 言語名が誤っていると期待した色分けや専用表示にならない。開始・終了のfenceと言語名を確認する | | `mermaid` | 図を描画する。内容の編集UIはない | 描画失敗時はエラーと元コードを表示する。まず短い図へ戻し、括弧やパイプを含むラベルを引用符で囲む | | 画像 `![説明](URL)` | Project Mediaのcanonical URLはProject文脈と取得権限があると画像になる。chatでは拡大プレビュー、共有文書ではMediaへのリンク | 外部画像URLは画像を自動取得せずリンクとして表示する。Project文脈がないと未解決表示、取得失敗時は再試行ボタン。URL、所属Project、閲覧権限を確認する | | 動画・PDF `[説明](URL)` | リンクを開いてMedia画面で閲覧する。本文内の動画プレーヤー・PDFビューアを作る構文ではない | 画像構文を流用せず通常リンクにする。削除済み・アクセス不能なMediaは開けない | | WikiLink `[[完全パス]]` | Project文脈がある表示面では文書チップとなり、プレビューや文書への移動に使える | 省略形・旧パスは警告、見つからない参照も未解決表示になる。文書の実在パスと権限を確認する。コード内ではリンク化しない | | `mindmap` | 色分けツリーの折りたたみ、祖先のハイライト、ソースのコピー | 未知タグは警告。構造エラーは行番号と元テキスト。スペースの深さ、タグ、本文を修正する | | `brainstorm` | カード、折りたたみ、表示順のSort切替、ソースのコピー | ratingは編集不可。不正キー・値は行番号と元テキスト。下記のキーと文字数・値の制限へ戻す | chatと公開ガイドは本文の単一改行も改行として表示する。共有文書のプレビューでは単一改行は通常Markdownの段落内改行として扱う。段落を分けたいときは空行を入れ、確実な強制改行が必要なときは行末に半角スペース2個を置く。 ## 通常Markdown・code・Mermaidの例 次を本文に貼ると、見出し、強調、引用、未完了・完了の表示、2列の表、ガイドへのリンクが表示される。 ```markdown ## 確認メモ **結論**と *仮説* を分ける。~~古い案~~ は取り消す。 > 共有前に参照先を確認する。 - [ ] 図を確認する - [x] 本文を読む | 対象 | 状態 | |---|---| | 原稿 | 確認中 | [共有ドキュメントのガイド](/ja/docs/shared-documents) ``` 次のコードは文字列として表示され、`hello`を出力するための実行は行われない。実行したい場合だけ、別の環境で内容を確認して実行する。 ````markdown ```javascript console.log("hello"); ``` ```` 次のMermaidは「原稿 → 確認 → 共有」の3ノードの図になる。これは作業手順の説明であり、共有操作を実行しない。 ````markdown ```mermaid flowchart LR A["原稿"] --> B["確認 (review)"] --> C["共有"] ``` ```` Mermaidはstrict設定で描画される。図内のHTMLやクリックによるスクリプト実行を前提にしない。 ## 画像・動画・PDF・WikiLinkの例 先にMediaを保存して、Media一覧から実際のcanonical URLを取得する。以下のUUIDは例なので、それぞれ自分の画像・動画・PDFのUUIDへ置き換える。短命な配信URLやローカルファイルの絶対パスは保存しない。 ```markdown ![完成画面](https://aachat.io/m/11111111-1111-4111-8111-111111111111) [操作動画](https://aachat.io/m/22222222-2222-4222-8222-222222222222) [報告書PDF](https://aachat.io/m/33333333-3333-4333-8333-333333333333) [[aachat/projects/example/demo/docs/notes/review.md]] ``` WikiLinkも、自分が参照する文書の完全パスへ置き換える。本文に書くと文書チップになるが、このガイドのコード例内では文字列として表示される。チップを作るためにファイルを新規作成したり、他Projectへのアクセス権を付与したりすることはない。 ## 公開ガイド・共有先での見え方 | 内容 | 公開ガイドのHTMLページ（このサイト） | 公開ガイドの「Markdown」表示 | 共有リンクの公開Markdown（`/share/…/*.md`） | |---|---|---|---| | 通常Markdown・code | 通常の本文・コードとして描画 | Markdownテキスト | Markdownテキスト。閲覧側ツールの対応に応じて表示 | | Mermaid・2構造化ブロック | 直接書かれた専用fenceは図・カード。このページの例は外側のfenceによってコード表示 | fenceと中身が残る。カードUIは付かない | fenceと中身が残る。aachatのカードUIや検証表示は配信されない | | 画像 | Project文脈がないのでProject Mediaは未解決表示。外部画像はリンク | 著者が書いた画像構文・URL | 共有対象として追跡できるMedia参照はtoken付き共有経路へ変換。対応する依存参照がないMediaは `Media unavailable` | | 動画・PDF | 通常リンク。リンク先のアクセス条件に従う | 著者が書いたリンク | 共有対象Mediaへのリンクを開くと画像・動画・PDF用の閲覧ページとoriginal downloadを提供 | | WikiLink | Project文脈がないため文書チップにはならない | WikiLinkの文字列 | 本文内のWikiLinkは文字列のまま。周囲に生成される文書・Sessionリンクとは別物 | 公開ガイドのMarkdown表示は原稿を読む経路であり、Projectを共有する機能ではない。共有リンクでも文書本文を編集したりSessionを開始したりするUIは付かない。外部のMarkdownツールへ渡した場合の図・HTML・リンクの扱いはそのツールに依存するので、必要な結論を普通の本文にも残す。 canonical Media URLを貼るだけでは、非メンバーに閲覧権限を渡せない。共有Markdownは有効な共有tokenとその範囲でアクセスを判定し、リンク先文書やMediaすべてを無条件に公開するものではない。外部画像参照をリンクやテキストにする経路もある。期待した画像や文書が開けなければ、本文の参照、Mediaの存在、共有範囲、期限・失効を作成者が確認する。共有の扱いは[共有ドキュメント](/ja/docs/shared-documents)と[Project Media](/ja/docs/media)、別のHTML成果物の公開は[Project HTML](/ja/docs/html)を参照する。 ## mindmap — 論点の構造を整理する `- [タグ] テキスト` をスペースのインデントで木構造にして書く。複雑な仕様・調査・判断を、FactとAssumptionを区別しながら整理するのに使う。 ````markdown ```mindmap title: 検索改善の判断 - [Goal] 検索の初回体験を良くする - [Question] 遅いのはどこか？ - [Fact] p95は800ms、インデックスは未使用 - [Assumption] ユーザーは300ms超で離脱する - [Option] インデックスを追加する - [Risk] 書き込みが遅くなる - [Decision] インデックス追加を先に検証する - [Next] ベンチマークをとる ``` ```` - タグは12種: `Goal` `Question` `Fact` `Assumption` `Concept` `Cause` `Option` `Tradeoff` `Risk` `Test` `Decision` `Next`。未知のタグは警告付きでそのまま表示される - `title:` 行は任意で、最初のリスト項目より前に1つだけ置ける - インデントはスペースのみ（**タブはエラー**）。リストマーカーは `-` を使う。最大200ノード - 表示は意味タグごとに色分けされた折りたたみツリー。ホバーで祖先パスがハイライトされる ## brainstorm — 案を並べて評価する question / background / ideas をYAML風に書く。仕様・UX・改善案の候補を発散し、人間に評価してもらう場面で使う。 ````markdown ```brainstorm question: オンボーディングの離脱をどう減らすか？ background: | 初回セットアップの完了率は60%。落ちるのはagent作成の手前。 ideas: - title: テンプレートagentを1clickで作る description: | 名前入力だけでDiscoverの定番agentを複製する。 rating: 4 - title: セットアップをWebUIだけで完結させる description: CLIインストールを後回しにできる導線にする。 ``` ```` - ルートキーは `question`（必須）/ `background`(任意) / `ideas`（必須）の3つだけ。ideaのキーは `title`（必須・50文字以内）/ `description`（必須・200文字以内）/ `rating`（任意・1〜5の整数）だけ - `background` とideaの `description` は `|` の複数行が書ける（description全体で200 Unicodeコードポイント以内）。`question` と `title` は単一行。ネスト・アンカー等のYAML機能は使えない。最大100案 - 表示はアイデアカードのグリッドで、ratingは `n/5` バッジ。**ratingをUIから付ける・変える機能はない**。評価を反映するにはMarkdown本文の `rating:` を編集する（並べ替えのSort切替は表示のみ） - 重要な決定はbrainstormのまま放置せず、Ask（[projects](/ja/docs/projects)）や仕様の文書に圧縮する ## ブロックを修正して再表示する エラー表示の行番号をブロック内の元テキストと照合し、本文を編集して保存・再表示する。閉じるfenceが欠けていないか、タブや未知キーがないかを確認する。長い説明はブロックの外の本文へ移す。タイトルや項目内には強調やリンクなどのinline Markdownを使えるが、見出し・引用・リスト・別のfenceなどのblock Markdownは入れない。警告付きで描画できても、タグの誤記を成果確認と取り違えず、原文を直す。編集権限がない読者は作成者へ修正を依頼する。 ## 関連ページ - 委任と複数agentの協働の実務 — [sessions](/ja/docs/sessions) - timelineの描画とWikiLink — [projects](/ja/docs/projects) - 共有ドキュメントの契約（ブロックを文書に書く場合） — [shared-documents](/ja/docs/shared-documents)