プロジェクトのドキュメント

プロジェクトごとに、文書を置く docs/ フォルダがあります。戦略、仕様、設計、メモなどを置いておく場所です。ボードのヘッダーの ドキュメント から、フォルダの中を見てファイルを読めます。ダイアログは表示するだけで、ファイルの編集はふだん使っているエディターで行います。ドキュメントはボードとは別に扱われます。文書が変わっても、タスクやエピック、ボードの履歴は変わりません。

ドキュメントを開く

ボードのヘッダーで ドキュメント を選びます。ダイアログの左にファイルの一覧、中央に選んだファイルが表示されます。

• ファイルの一覧。 プロジェクトの docs/ にあるフォルダとすべてのファイルを、フォルダとファイルを区別せずに名前の順で表示します。01_ のような番号で始まる名前は、その番号の順に並びます。ドットで始まる名前とシンボリックリンクは表示しません。一覧の右端のつまみをドラッグすると、一覧の幅を変えられます。名前が長いときは省略せずに全体を表示し、一覧を横にスクロールできます。
• フォルダを開く。 見出し ファイル の右端のアイコンで、プロジェクトの docs/ フォルダを、Finder などコンピュータのファイルマネージャで開けます。表示されるのはコンピュータの画面だけで、電話の幅の画面には出ません。開けなかったときは、見出しの下に短いメッセージが出ます。
• 本文。 ファイルを選ぶまでは、中央に ファイルを選択してください と表示されます。ファイルは選ぶたびにディスクから読み込みます。

本文の表示は、ファイルの種類で変わります。

ファイル	表示
Markdown（.md）	整形した文書。表、コードブロック、Mermaid の図、画像も表示します。
MDX（.mdx）	コードを実行した文書。文字組みとテーマは Markdown と同じです。
画像（.png・.jpg・.jpeg・.webp・.gif・.avif・.svg）	画像そのもの。
それ以外（.pen、.json、.txt など）	表示対象外のファイルです。 とファイル名。

• フロントマター。 Markdown と MDX の先頭にある --- で囲んだ YAML は、本文の上の フロントマター の枠に分けて表示します。最初は項目数だけを見せて閉じています。選ぶと中身を表示します。
• 文書の中の画像。 ![図](images/flow.png) のように相対パスで書いた画像は、そのファイルのあるフォルダを基準に探します。http と https のアドレスの画像は、ボードと同じように読み込みます。
• 文書の中のリンク。 [戦略](business/01_STRATEGY.mdx) のように相対パスで書いたリンクを選ぶと、そのファイルをダイアログで開きます。パスは、そのファイルのあるフォルダを基準に読みます。フォルダへのリンクは、その中の README.md を開きます。ファイルの一覧は、そのファイルの上のフォルダを開いて、ファイルを表示します。http と https のリンクは新しいタブで開きます。相対パスのリンクの先に docs のファイルがないときは、フッターに リンク先のファイルが見つかりません。 と表示します。ボードの画面そのものが移動することはありません。

ファイルが一つもないときは このプロジェクトにはDocsがありません と表示し、データ領域の中のフォルダのパス shared/projects/<project-id>/docs/ と、パスをコピーするボタンを出します。

電話の幅の画面では、ファイルの一覧が画面いっぱいに表示されます。ファイルを選ぶと一覧の代わりに内容が表示され、フッターの ファイル で一覧に戻れます。

MDX

.mdx は、JSX と JavaScript の式を書ける Markdown です。ダイアログは中のコードを実行して、結果を表示します。

• Markdown は .md と同じ GitHub 形式です。表・タスクリスト・取り消し線・自動リンクを描画します。
• 標準の HTML 要素、{tasks.length} のような式、export で宣言した値や関数が使えます。
• 使える部品は登録したものだけです。<Chart /> のように登録されていない部品は 未登録の部品: Chart と表示し、ほかの部分は描画します。
• 閉じタグの抜けなど MDX の誤りや、式の失敗は、文書の代わりに 実行エラー: … の枠を表示します。
• 色を var(--r-text) や var(--r-accent) のようにボードのテーマの変数で書くと、ライトとダークの両方のテーマに合わせて表示されます。

コードは、ボードのデータにもネットワークにも届かない隔離された枠の中で実行します（ドキュメントの MDX）。

ファイルを編集する

ダイアログではファイルを編集しません。フッターの エディターで開く を選ぶと、選んだファイルを、コンピュータがその種類のファイルに使うアプリ（テキストエディターなど）で開きます。編集と保存はそのアプリで行ってください。開けなかったときは、フッターの左に ファイルを開けませんでした。 と表示します。

ファイルやフォルダの追加、名前の変更、移動、削除は、フォルダそのものに対して、Finder やエクスプローラー、テキストエディター、エージェントで行います。

agboard --project "My project" workspace --json

結果の folder がプロジェクトのフォルダで、文書はその中の docs/ にあります。

ダイアログの外での変更

ダイアログを開いている間は、docs/ フォルダの変化に追従します。

• ファイルやフォルダを作ったり消したりすると、一覧に現れたり、一覧から消えたりします。
• 開いているファイルが変わると、本文が新しい内容になり、フッターの左に ファイルが変更されたため、表示を更新しました と時刻を表示します。
• 開いているファイルが削除されると、最後に表示した内容はそのまま残り、フッターの左に このファイルは削除されました と時刻を表示します。

制限

• 表示できる Markdown と MDX は 2 MiB までの UTF-8 のテキストです。画像は 10 MiB までです。
• docs/ はプロジェクトを作ったときに、アプリの言語で書いた短い README.md と一緒に作られます。docs/ のない古いプロジェクトでは、サーバーの起動時に作ります。削除した README.md を作り直すことはありません。
• agboard project rm でプロジェクトを削除すると、docs/ フォルダも削除されます。残したいものは先にコピーしてください。
• モバイルモニターではドキュメントを表示しません。

次に読む

• 編集と画像の添付：タスクとエピックの編集。
• データとバックアップ：データ領域の場所とバックアップの方法。