Astro Markdown Visual Editor
Astroの記事用の .md を、記事情報フォームとビジュアル画面で編集するデスクトップ版VS Code拡張機能です。元のMarkdownが正本で、保存・自動保存・未保存表示・Undo / RedoはVS Codeの文書管理と連動します。通常のMarkdownソース編集は既定のままです。
インストールと起動
- VS Code 1.96以降のデスクトップ版を使用します。初回の実機検証はmacOSで行っています。
- 拡張機能ビューの
… → VSIXからのインストール… で astro-markdown-visual-editor-0.1.0.vsix を選択します。
- Astroプロジェクトのフォルダーを開き、編集する
.md を右クリックして ブログ記事をビジュアル編集 を選びます。
- 記事情報や本文を編集し、
⌘S / Ctrl+S または通常の保存メニューで保存します。
コマンドパレットの ブログ記事をビジュアル編集、エディターの エディターを開く方法の選択 からも起動できます。コマンドパレットでは対象の .md をソースエディターで開いて選択してください。.mdx は対象外です。
CLIでインストールする場合(code がPATHにある環境):
code --install-extension ./astro-markdown-visual-editor-0.1.0.vsix
ビジュアル画面上部の ソースを開く で通常のテキスト編集に戻れます。サイトの公開、Git操作、Astroビルドなどは既存の手順で行ってください。
本文の編集
ツールバーで段落、H1〜H6、太字、斜体、リンク、インラインコード、箇条書き、番号付きリスト、引用、コードブロック、水平線、画像を挿入できます。見出し・リストは表示された文章を直接編集します。
⌘B / Ctrl+B: 太字
⌘I / Ctrl+I: 斜体
⌘ / Ctrl + バッククォート: インラインコード
- リスト内の
Enter: 次の項目、Tab / Shift+Tab: インデント変更
- コードブロック内ではツールバーに言語の入力欄が表示されます。
⌘Enter / Ctrl+Enter でコードの後に段落を作れます。
⌘Z / Ctrl+Z: 元に戻す、⌘Shift+Z / Ctrl+Shift+Z または Ctrl+Y: やり直す
- コピー・切り取り・貼り付けは通常のキーボード操作を使います。
日本語変換中はMarkdownへの変換・送信と外部更新による画面の差し替えを待機します。自分の変更に対する応答で本文を再生成せず、カーソルと選択範囲を保ちます。本文の変更は先頭の入力と、その後の約350msの入力のまとまりでTextDocumentに反映します。
表示は文章構造を確認するためのものです。Astroサイトの実際のデザインは再現しません。VS Codeのライト・ダークテーマに追従します。
記事情報と設定
初期フィールドは title、description、pubDate、tags、heroImage、draft です。Astro共通の必須キーとしては扱いません。未入力の項目は追加せず、空文字・false・未設定を区別します。未設定に戻す でキーを削除できます。タグは1行に1件入力します(空行は除きます)。
ワークスペースの .vscode/settings.json に設定できます。
{
"astroMarkdown.fields": [
{ "key": "title", "label": "タイトル", "type": "string" },
{ "key": "summary", "label": "概要", "type": "multiline" },
{ "key": "date", "label": "公開日", "type": "date" },
{ "key": "categories", "label": "カテゴリー(1行に1件)", "type": "stringArray" },
{ "key": "cover", "label": "カバー画像", "type": "image" },
{ "key": "draft", "label": "下書き", "type": "boolean" }
],
"astroMarkdown.imageDirectory": "assets/{name}"
}
キーはトップレベルのYAMLキーです。. を含むキーもその文字列のまま扱い、ネストのパスには展開しません。同じキーを複数設定できません。スキーマの自動解析は行いません。
- 本文だけの編集では、frontmatterの元の文字列をそのまま保持します。
- 記事情報は
yaml のDocument / ASTを編集し、未知のキー・ネスト・コメント・アンカーなどを保持します。記事情報を変更すると、YAMLの空白や配列の表記が正規化されることがあります。
- 日付は文字列として保持します。既存の日付に時刻が含まれる場合は、日付入力欄に切り詰めずテキストで表示します。
- 既存の値が設定と異なる型(例: 数値のタイトルやオブジェクト型の画像)なら、そのフィールドを無効にしてソース編集を案内します。
- YAMLが不正、重複キーがある、トップレベルがマップでない、未対応タグがある場合は、本文と記事情報の両方を読み取り専用にします。
- frontmatterがない記事も編集できます。フォームに値を入力したときだけfrontmatterを追加します。
画像
画像 ボタンからPNG・JPEG・WebP・GIFを選択するか、OSから画像ファイルを本文へ1枚ずつドロップします。元のファイルを残したままコピーし、UUIDを使った名前と元形式の拡張子で保存します。リサイズ・圧縮・形式変換は行いません。上限は1ファイル20MBです。
既定の構成:
posts/
├── my-post.md
└── assets/
└── my-post/
└── <UUID>.png
挿入する画像の参照パスは ./assets/my-post/<UUID>.png です。代替テキストは挿入時に入力できます。
コピー先は記事のフォルダーを基準とし、{name} を記事の拡張子を除くファイル名に置換します。ワークスペース外を指す設定・シンボリックリンクへのコピーは拒否します。コピーにはローカルのワークスペースを開く必要があります。画像を本文から削除しても画像ファイルは残ります。ダイアログをキャンセルした場合も、コピー済みの画像は自動削除しません。
画像URL / 説明 でHTTPS URLを挿入できます。既存画像をダブルクリックして、参照先・代替テキストを編集できます。画像にカーソルで移動して選択した状態から同じボタンでも編集できます。heroImage 等のフォームはパス・URLの文字列入力です。
既存画像の相対パスは記事のファイルを基準に解決し、VS Codeの asWebviewUri で表示します。変換した表示用URIはMarkdownには保存しません。画像が読めない場合も、元のパスと代替テキストを表示します。表示可能なローカルリソースは、記事のワークスペース内(単独ファイルでは記事のあるフォルダー内)に限ります。
外部のHTTPS画像を表示すると、その画像のホストにアクセスします。 本文を外部サービスに送信する処理、テレメトリー、外部ストレージ連携はありません。HTTPS以外の外部画像、Astroの public/ 基準のパス、独自エイリアスの表示は対象外ですが、既存の参照文字列は保持します。クリップボードの画像データ貼り付けは必須対応に含めていません。
対応構文とデータの保全
| 構文 |
対応 |
| 段落・ソフト改行・明示的改行 |
対応 |
| 見出しH1〜H6 |
対応 |
| 太字・斜体・インラインコード |
対応 |
| リンク・画像・代替テキスト・タイトル |
対応 |
| 箇条書き・番号付きリスト・入れ子 |
対応 |
| 引用・水平線 |
対応 |
| 言語指定付きコードブロック・インデントコード |
対応 |
| 表・HTML・JSX・数式・ディレクティブ |
読み取り専用、ソースへ誘導 |
| タスクリスト・取り消し線・脚注 |
読み取り専用、ソースへ誘導 |
| MDX |
対象外 |
| 任意の独自構文やプラグイン |
対応を保証しない |
remark の構文木で対応外構文を検出します。コード内のHTML・数式・ディレクティブなどを単純検索で誤検出しません。さらにMarkdownの往復変換でProseMirrorの文書構造とCommonMarkのHTML表現を比較し、安全に保持できない文書を読み取り専用にします。記事内HTMLは実行しません。未知のプロジェクト固有構文をすべて自動識別できるわけではないため、独自構文を含む記事はソースで編集してください。
未編集のファイルは変更しません。対応本文を編集すると、リスト記号、強調記号、コードのフェンスなどが正規化される場合があります。改行コードと末尾改行の有無、本文中のコード内容、リンク先と画像参照は可能な限り保持します。画像alt内の装飾は代替テキストの意味を保つ文字列に正規化します。
文書のバージョンが一致しない変更を適用しません。ソース・外部更新を優先して再同期し、競合前の未送信入力は画面下部の 競合前の入力を確認・コピー に退避します。自動でマージせず、必要な内容をコピーして反映してください。退避内容はVS CodeのWebview状態にも保存します。
未信頼ワークスペースでは読み取り専用にし、本文編集・記事情報編集・画像コピーを無効化します。CSPでスクリプトを制限し、通信先を画像表示以外に許可しません。
開発とテスト
Node.js 22以降とnpmを推奨します(検証環境はNode.js 24)。
npm ci
npm run check
npm test
npm run build
npm run package
F5 の 拡張機能を起動 で fixtures/ を開いたExtension Development Hostを起動できます。生成物は dist/、ローカルインストール用VSIXはルートに出力します。MarketplaceやWebサイトへの公開コマンドはありません。
npm run test:ui
# テスト専用フォルダーにVSIXをインストールした後、パッケージ版を検証
npm run test:vsix
macOSの /Applications/Visual Studio Code.app にあるVS Codeを、隔離した .test-workspace/ プロファイルで起動します。Playwrightで実際のWebviewを操作し、ホスト側のTextDocumentと照合します。既存のユーザー設定や拡張機能インストール先は使いません。画像のHTTPS応答はテスト内で差し替え、外部サーバーに依存させていません。artifacts/ に結果JSON・スクリーンショット・ログを出力できます。
src/extension.ts: CustomTextEditorProvider、WorkspaceEdit、信頼・保存・画像のメッセージ処理
src/core/: Markdown検証・変換、YAML編集、画像コピー
src/webview/: ProseMirror、記事情報フォーム、同期と競合退避
tests/: 変換・frontmatter保全・対応外構文・パス境界のテスト
fixtures/: 動作確認用MarkdownとPNG
VALIDATION.md: 検証結果と制限事項(ソースとVSIXに同梱)
選定時には ProseMirrorのMarkdown実装、Markdownの公式サンプル、EditorViewのcomposition対応、YAML Document API、VS Code Custom Editor API を確認しました。ProseMirrorの公式Markdownスキーマを基に、ソフト改行と画像altの保持だけを拡張しています。
同梱ライブラリのライセンスは dist/THIRD_PARTY_NOTICES.txt に記載しています。