Markdownエディタ「Bokuchi」の使用者向けドキュメントサイトを構築する。 対象読者はエンジニアに限らず、初めてMarkdownに触れるユーザーも含む。 「Bokuchi をダウンロードした人が、迷わず使い始められること」がゴール。
| 項目 | 内容 |
|---|---|
| URL | doc.bokuchi.com |
| フレームワーク | Astro（Starlightテーマ推奨） |
| ホスティング | GitHub Pages |
| リポジトリ | Bokuchi-Editor Organization 内に新規作成 |
| CI/CD | GitHub Actions で main ブランチ push 時に自動ビルド・デプロイ |
| 言語 | 日本語・英語（i18n対応。将来的に多言語拡張の余地を残す） |
| 本体サイト | bokuchi.com（既存の紹介サイト。こちらとは別運用） |
Tauri 2 + React + Rust で構成されたクロスプラットフォーム（Windows / macOS / Linux）対応のマルチタブ Markdown エディタ。オフラインで完結し、外部サービスへの依存がない。14言語のUI対応、5種類のテーマ、変数システム、フォルダツリー、アウトライン、テーブル変換など豊富な機能を持つ。
このサイトの読者像を以下のように定義する。コンテンツはすべて最も初心者寄りのユーザーでも理解できるレベルを基準とする。
| ペルソナ | 説明 |
|---|---|
| Markdown初心者 | 「Markdownって何？」の段階。議事録やメモを書きたいが記法を知らない |
| Markdownライトユーザー | 基本記法は知っているが、エディタの高度な機能は使いこなせていない |
| ドキュメント作成担当者 | 社内文書・マニュアル作成にBokuchiを使いたい非エンジニア |
| 既存のエディタからの移行者 | Typora, Obsidian, VS Code 等から乗り換えを検討している人 |
以下の構成をベースとする。各ページの詳細は「4. コンテンツ仕様」で後述する。
doc.bokuchi.com/
├── / ← トップページ（ようこそ）
│
├── getting-started/ ← はじめに
│ ├── installation/ ← インストール
│ ├── first-document/ ← はじめてのドキュメント作成
│ └── ui-overview/ ← 画面の見方
│
├── guides/ ← 使い方ガイド
│ ├── markdown-basics/ ← Markdown 基本記法
│ ├── file-operations/ ← ファイル操作
│ ├── tabs/ ← タブ管理
│ ├── editor-and-preview/ ← エディタとプレビュー
│ ├── search-and-replace/ ← 検索と置換
│ ├── markdown-toolbar/ ← Markdown ツールバー
│ ├── outline/ ← アウトライン（目次）パネル
│ ├── folder-tree/ ← フォルダツリー（エクスプローラー）
│ ├── table-conversion/ ← テーブル変換（HTML/CSV → Markdown）
│ ├── variables/ ← 変数システム
│ ├── themes/ ← テーマの変更
│ ├── zoom/ ← ズーム操作
│ ├── export/ ← エクスポート（HTML出力）
│ └── settings/ ← 設定のカスタマイズ
│
├── reference/ ← リファレンス
│ ├── keyboard-shortcuts/ ← キーボードショートカット一覧
│ ├── supported-languages/ ← 対応言語一覧
│ ├── markdown-cheatsheet/ ← Markdown チートシート
│ └── system-requirements/ ← 動作環境
│
├── faq/ ← よくある質問
│
└── changelog/ ← 更新履歴
各ページに記載すべき内容と注意事項を定義する。
- Bokuchi の一言紹介（「無料・オフラインで使えるMarkdownエディタ」）
- 主要な特徴を3〜4つ、アイコン付きで簡潔に紹介
- 「はじめての方はこちら」のCTA（getting-started へ誘導）
- ダウンロードリンク（bokuchi.com または GitHub Releases への導線）
- Windows / macOS / Linux ごとのインストール手順
- macOS の場合：Gatekeeper の警告への対処法（「開発元が未確認」の許可方法）
- スクリーンショット付きで手順を説明
- 「インストール後に最初に表示される画面」の説明
- Bokuchi を起動してから最初のドキュメントを保存するまでの一連の流れ
- ステップバイステップ形式（1. 起動する → 2. 文字を入力する → 3. プレビューを確認する → 4. 保存する）
- Markdownを知らない人向けに「左に書くと右に整形されて表示される」の基本概念を説明
- スクリーンショット必須
- 画面各部の名称と役割を図解（番号付きの注釈画像）
- タブバー
- エディタ（左パネル）
- プレビュー（右パネル）
- Markdownツールバー
- ステータスバー（行・列・文字数・ズーム・テーマ）
- フォルダツリー（左サイドパネル）
- アウトライン（右サイドパネル）
- 3つの表示モード（分割ビュー / エディタのみ / プレビューのみ）の紹介
このページは特に重要。非エンジニアがMarkdownを学ぶ入口になる。
- 見出し（# / ## / ###）
- 太字・斜体・取り消し線
- リスト（箇条書き・番号付き・チェックボックス）
- リンクと画像
- 引用
- コードブロック・インラインコード
- 表（テーブル）
- 水平線
各記法について以下の形式で統一する：
【記法名】
- 何に使うか（用途の説明）
- 書き方（Markdown記法）
- 表示結果（レンダリング後の見た目）
- Bokuchi での入力方法（ツールバーのボタンでも入力できることを案内）
- 新規作成 / 開く / 保存 / 名前を付けて保存
- 最近使ったファイル（検索・フィルター機能付き）
- ファイルの外部変更検知（他のアプリで編集した場合のリロード確認）
- ファイルが見つからない場合の挙動（セッション復元時）
- ドラッグ＆ドロップでの複数ファイルオープン
- オートセーブ（3秒デバウンスの自動保存。設定でON/OFF可能）
- 複数ファイルのタブ表示
- タブの並べ替え（ドラッグ＆ドロップ）
- タブの右クリックメニュー
- 未保存インジケータ（バッジ表示）
- 水平タブ / 垂直タブの切り替え
- タブ間の移動ショートカット（Ctrl+Tab / Ctrl+Shift+Tab）
- 分割ビュー / エディタのみ / プレビューのみの切り替え方法
- 同期スクロール（エディタとプレビューのスクロール位置が連動）
- プレビュー内のチェックボックスはクリックで切り替え可能
- プレビュー内のリンクの動作
- コードブロックのシンタックスハイライト（190以上の言語対応）
- 検索パネルの開き方
- マッチ件数の表示
- マッチ間の移動（次へ / 前へ）
- オプション：大文字小文字の区別 / 単語単位 / 正規表現
- 単一置換 / 全置換
- 各ボタンの説明（見出しH1〜H3 / 太字 / 斜体 / 取り消し線 / リスト各種 / リンク / 画像 / コード / 引用 / 水平線 / テーブル）
- 「Markdown の記法を覚えなくても、ボタンを押すだけで装飾できる」ことを強調
- テキスト選択中にボタンを押すと、選択範囲に装飾が適用されることの説明
- 見出し構造をツリー表示
- クリックでエディタ内の該当箇所にジャンプ
- 表示モード：常時表示（persistent）/ オーバーレイ（overlay）/ OFF
- ショートカット：Ctrl+Shift+O
- フォルダを開いてファイル一覧を表示
- ファイルクリックでタブに開く
- 表示モード：常時表示（persistent）/ オーバーレイ（overlay）/ OFF
- 垂直タブとの統合モード
- Markdownファイルのみ / 全ファイル表示の切り替え
- ショートカット：Ctrl+Shift+E
- HTML テーブルをペーストすると Markdown テーブルに自動変換
- TSV / CSV データも Markdown テーブルに変換可能
- 動作モード：自動変換（auto）/ 確認ダイアログ（confirm）/ OFF
- Shift+Cmd/Ctrl+V でプレーンテキストとして貼り付け（変換バイパス）
- 設定での切り替え方法
Bokuchi 独自機能のため、丁寧に説明する。
- 変数とは：同じ値を複数箇所で使い回す仕組み。
{{変数名}}で参照 - ファイルローカル変数：ファイル内で
<!-- @var 名前: 値 -->で定義 - グローバル変数：設定パネルから登録。全ファイル共通
- 優先順位：ローカル変数 > グローバル変数 > 未定義（そのまま表示）
- 使用例：
- レポートテンプレート（タイトル・日付・著者を変数化）
- 社内文書（会社名・部署名をグローバル変数に登録）
- 変数のエクスポート / インポート（YAML形式）
- 変数を展開した状態で保存する機能
- 5種類のテーマ：Default / Dark / Pastel / Vivid / Darcula
- 設定画面からの変更方法
- ステータスバーからのクイック切り替え
- 各テーマのスクリーンショット（並べて比較できると良い）
- ズームイン / ズームアウト / リセット
- ショートカット：Cmd/Ctrl + Plus / Minus / 0
- ステータスバーのズームボタン
- 範囲：50% 〜 200%
- ズーム設定はセッション間で保持される
- HTMLエクスポート：プレビュー内容をスタイル付きHTMLファイルとして出力
- シンタックスハイライト付きコードブロックの保持
- 相対パスの画像はデータURIとして埋め込み
- 変数を展開した状態での保存
- 設定画面の開き方（Cmd/Ctrl+, または F1）
- 設定カテゴリの説明：
- 外観：テーマ
- エディタ：フォントサイズ / 行番号 / タブサイズ / 折り返し / ミニマップ
- インターフェース：言語 / タブレイアウト / ズーム / パネル表示モード
- 詳細設定：オートセーブ / 空白文字表示 / テーブル変換モード
- 設定のエクスポート / インポート（JSON形式）
- 設定のリセット
表形式で一覧化する。macOS / Windows・Linux でキー表記を分けること。
| カテゴリ | 操作 | macOS | Windows / Linux |
|---|---|---|---|
| ファイル | 新規作成 | Cmd+N | Ctrl+N |
| ファイル | 開く | Cmd+O | Ctrl+O |
| ファイル | 保存 | Cmd+S | Ctrl+S |
| ファイル | 名前を付けて保存 | Cmd+Shift+S | Ctrl+Shift+S |
| ファイル | 最近使ったファイル | Cmd+R | Ctrl+R |
| 表示 | 分割ビュー | Ctrl+Shift+1 | Ctrl+Shift+1 |
| 表示 | エディタのみ | Ctrl+Shift+2 | Ctrl+Shift+2 |
| 表示 | プレビューのみ | Ctrl+Shift+3 | Ctrl+Shift+3 |
| 表示 | 表示モード切替 | Ctrl+Shift+V | Ctrl+Shift+V |
| 表示 | ズームイン | Cmd+Shift+Plus | Ctrl+Shift+Plus |
| 表示 | ズームアウト | Cmd+Minus | Ctrl+Minus |
| 表示 | ズームリセット | Cmd+0 | Ctrl+0 |
| パネル | エクスプローラー | Ctrl+Shift+E | Ctrl+Shift+E |
| パネル | アウトライン | Ctrl+Shift+O | Ctrl+Shift+O |
| ナビ | 次のタブ | Ctrl+Tab | Ctrl+Tab |
| ナビ | 前のタブ | Ctrl+Shift+Tab | Ctrl+Shift+Tab |
| その他 | 設定 | Cmd+, | Ctrl+, |
| その他 | ヘルプ | F1 | F1 |
- UI対応14言語の一覧表（言語名・コード・ネイティブ表記）
- 言語の切り替え方法への導線
- 印刷して手元に置ける形式を意識
- 記法 → 表示結果の2カラム形式
- GFM（GitHub Flavored Markdown）拡張記法も含む
- 対応OS：Windows / macOS / Linux
- 推奨スペック（軽量アプリなので最低限で動く旨を記載）
- オフライン動作であること
- シングルインスタンス制約（アプリは同時に1つだけ起動）
想定するQ&Aの例：
- Q: Markdownとは何ですか？
- A: テキストに簡単な記号をつけて装飾する書き方です。Bokuchiでは記号を覚えなくてもツールバーから操作できます。
- Q: ファイルはどこに保存されますか？
- A: ユーザーが指定した場所に保存されます。クラウドへの自動同期はありません。
- Q: インターネット接続は必要ですか？
- A: 不要です。完全にオフラインで動作します。
- Q: 他のエディタで作ったMarkdownファイルは開けますか？
- A: はい。.md / .txt / .markdown ファイルに対応しています。
- Q: 自動保存はありますか？
- A: はい。設定でON/OFFが切り替えられます（デフォルトON、3秒間隔）。
- Q: テーマを変更するには？
- A: 設定画面、またはステータスバーのテーマ表示をクリックして変更できます。
- Q: アプリを閉じてもタブは復元されますか？
- A: はい。前回開いていたタブと設定がそのまま復元されます。
- Q: macOS で「開発元が未確認」と表示されます
- A: システム環境設定 > セキュリティとプライバシー から許可してください。（手順をインストールページに記載）
- Q: 変数とは何ですか？
- A: 同じテキストを複数箇所で使い回すための仕組みです。詳しくは変数ガイドをご覧ください。
- Q: PDF出力はできますか？
- A: 現在はHTML出力に対応しています。PDF出力は今後の実装予定です。
- バージョンごとの変更内容を時系列で記載
- GitHub Releases の内容をベースに、使用者向けの表現に書き換える
- 「新機能」「改善」「修正」のカテゴリ分け
- 親しみやすく、丁寧に。 技術用語をいきなり使わない
- 専門用語を使う場合は初出時に簡単な説明を添える
- 命令形ではなく「〜してください」「〜できます」の表現
- 「まず」「次に」「最後に」のようなステップ表現を多用する
- スクリーンショットは各主要ページに必須
- 操作手順にはステップ番号 + スクリーンショットの組み合わせ
- UI の各部名称には注釈付き図解を使用（矢印・番号ラベル）
- テーマ紹介ページには5テーマの比較スクリーンショット
- ダーク/ライトモード対応のデザイン（Starlightのデフォルトで対応可能）
- サイドバーに常時ページ一覧を表示（Starlightの標準機能）
- パンくずリスト表示
- 各ページ下部に「次のステップ」「関連ページ」へのリンク
- トップレベルの検索機能（Starlightの全文検索を有効化）
- スマートフォンからも閲覧可能であること（Starlightのデフォルトで対応）
- Astro + Starlight テーマ
- Starlight を推奨する理由：
- ドキュメントサイトに特化した設計
- i18n（多言語）サポートが組み込み
- 全文検索が標準装備
- サイドバー・パンくず・ダークモードなどが設定のみで利用可能
- GitHub Pages へのデプロイが公式ドキュメントでサポート
bokuchi-docs/ ← リポジトリ名（提案）
├── .github/
│ └── workflows/
│ └── deploy.yml ← GitHub Pages デプロイ用ワークフロー
├── src/
│ ├── content/
│ │ └── docs/
│ │ ├── en/ ← 英語コンテンツ
│ │ └── ja/ ← 日本語コンテンツ
│ └── assets/
│ └── images/ ← スクリーンショット等
├── astro.config.mjs
├── package.json
└── README.md
mainブランチへの push をトリガーに自動ビルド・デプロイ- Astro の
astro buildで静的ファイルを生成 - 生成物を GitHub Pages にデプロイ
- Astro 公式の GitHub Pages デプロイガイドに準拠
doc.bokuchi.comを GitHub Pages のカスタムドメインとして設定- DNSに CNAME レコードを追加（
doc.bokuchi.com→bokuchi-editor.github.io） - リポジトリの GitHub Pages 設定でカスタムドメインを指定
- HTTPS の自動有効化（GitHub Pages 標準機能）
- 初期リリースは日本語・英語の2言語
- Starlight の i18n 機能を使用し、言語切替UIを表示
- デフォルト言語：英語（
/= 英語、/ja/= 日本語） - 将来的に Bokuchi 本体が対応する14言語への拡張を視野に入れた構成
- 「なぜ」から説明する — 機能の説明の前に、どんな場面で役立つかを一言添える
- スクリーンショットは最新版で撮影 — バージョンが上がったら更新する運用ルールを決める
- プラットフォーム差異を明示 — ショートカットキーは macOS / Windows・Linux を併記。macOS では Cmd、Windows/Linux では Ctrl
- 一文を短く — 1文40〜60文字を目安に。長い文は分割する
- 箇条書きを活用 — 長い段落より箇条書きの方が読みやすい
- 「できます」を多用する — 「〜しなければならない」ではなく「〜できます」「〜すると便利です」
- 内部リンクを積極的に — 関連機能のページへリンクし、回遊性を高める
- 形式：PNG（透過なし）
- サイズ：幅1200px程度（Retina対応で2倍撮影 → 表示は半分）
- テーマ：Default テーマ（Light）で統一（Dark テーマの説明時のみ Dark で撮影）
- 注釈：矢印や番号は画像内ではなく、Starlightのキャプション機能や本文で補足
- ファイル名：
{セクション}-{内容}-{連番}.png（例：getting-started-save-01.png）
| フェーズ | 内容 | 備考 |
|---|---|---|
| Phase 1 | プロジェクトセットアップ（Astro + Starlight + GitHub Pages + CI） | 空のサイトがデプロイされ、doc.bokuchi.com でアクセスできる状態 |
| Phase 2 | 「はじめに」セクション完成 | インストール〜最初のドキュメント作成〜画面の見方 |
| Phase 3 | 「使い方ガイド」コア機能完成 | Markdown基本記法 / ファイル操作 / エディタとプレビュー / ツールバー / 設定 |
| Phase 4 | 「使い方ガイド」残り + リファレンス完成 | タブ / 検索 / アウトライン / フォルダツリー / テーブル変換 / 変数 / テーマ / ズーム / エクスポート + ショートカット一覧 / チートシート等 |
| Phase 5 | FAQ + 更新履歴 + 全体レビュー | 全ページのリンク整合性・スクリーンショット・多言語対応の確認 |
- アプリ内ヘルプ：Bokuchi本体にはF1で開くヘルプダイアログがあり、「はじめに」「機能紹介」「変数」「キーボードショートカット」「チュートリアル」の5セクションが実装済み。ドキュメントサイトのコンテンツはこれをベースに大幅に拡充する位置付け
- README：GitHubリポジトリのREADMEに機能一覧・変数システム・ロードマップが記載されている
- 本体サイト：bokuchi.com はプロジェクト紹介・ダウンロード導線を担当。ドキュメントサイトとは役割を分離
ファイル操作
- 新規作成 / 開く / 保存 / 名前を付けて保存
- 最近使ったファイル（検索・フィルター付き、最大20件）
- 外部ファイル変更検知・リロード確認
- ファイル未検出時のグレースフル処理
- 複数ファイルのドラッグ＆ドロップオープン
- オートセーブ（3秒デバウンス、設定でON/OFF）
- セッション状態の永続化・復元
編集・コンテンツ
- リアルタイムMarkdownプレビュー
- 同期スクロール
- インタラクティブチェックボックス（プレビュー内でクリック切替）
- 検索＆置換（マッチ数表示 / 大小区別 / 単語単位 / 正規表現 / 一括置換）
- Markdownツールバー（H1-H3 / 太字 / 斜体 / 取消線 / リスト各種 / リンク / 画像 / コード / 引用 / 水平線 / テーブル）
- シンタックスハイライト（190+言語対応）
- 行番号表示（ON/OFF）
- 折り返し表示（ON/OFF）
- ミニマップ（ON/OFF）
- 空白文字表示（ON/OFF）
- タブサイズ設定
- フォントサイズ設定
変数システム
- グローバル変数（設定パネルで管理、全ファイル共通）
- ファイルローカル変数（
<!-- @var name: value -->形式） - 優先順位：ローカル > グローバル
- 変数のYAMLエクスポート / インポート
- 変数展開済み保存
レイアウト・表示
- 分割ビュー / エディタのみ / プレビューのみ
- 表示モードのローテーション切替
- 水平タブ / 垂直タブ
- タブのドラッグ＆ドロップ並び替え
- タブの右クリックメニュー
- 未保存バッジ表示
アウトライン（目次）
- 見出しのツリー表示
- クリックで該当箇所にジャンプ
- 表示モード：persistent / overlay / off
フォルダツリー（エクスプローラー）
- フォルダ構造のツリー表示
- 表示モード：persistent / overlay / off
- 垂直タブとの統合モード
- サブディレクトリの遅延読み込み
- アクティブファイルのハイライト
- Markdown ファイルのみ / 全ファイル表示の切り替え
テーブル変換
- HTML テーブル → Markdown テーブル
- TSV/CSV → Markdown テーブル
- モード：auto / confirm / off
- プレーンテキスト貼り付け（変換バイパス）
ズーム
- ズームイン / ズームアウト / リセット
- 範囲：50% 〜 200%
- ステータスバーからの操作
- ズーム設定の永続化
テーマ
- Default / Dark / Pastel / Vivid / Darcula
- 設定画面 / ステータスバーから切替
- テーマ設定の永続化
設定
- 外観 / エディタ / インターフェース / 詳細設定
- 設定のJSON エクスポート / インポート
- 設定リセット
エクスポート
- HTML エクスポート（スタイル埋め込み）
- シンタックスハイライト保持
- 画像のデータURI埋め込み
多言語対応
- 14言語のUI対応
システム統合
- シングルインスタンス制約
- ネイティブファイルダイアログ
- macOS メニューバー統合
- ファイル関連付け
- 完全オフライン動作
- 自動アップデートチェック
本提案書は Bokuchi リポジトリの現在の実装状態（2026年3月時点）に基づいています。