Markda の使い方

1. インストールと開き方

1. Visual Studio Marketplace から Markda をインストールします。VS Code の拡張機能ビューで「Markda」と検索しても見つかります。クイックオープン（Ctrl+P）で ext install tetsuji16.markda と入力してもインストールできます。
2. Markdown ファイルを開きます。対応する拡張子は .md、.markdown、.mdown、.mkd、.mkdn、.mdwn、.txt です。
3. VS Code のテキストエディターで開いた場合は、コマンドパレットで markda: markdaで開く を実行するか、エディタータブのメニューから Reopen Editor With…（エディターを選択して開き直す）→ Markda を選びます。

Markda をいつものエディターにする

markda: ファイルの関連付けを構成 を実行し、Markda で開く拡張子を選びます。ユーザー全体か、このワークスペースだけかを選べます。設定は VS Code の workbench.editorAssociations に保存されるので、直接書いてもかまいません。

"workbench.editorAssociations": {
  "*.md": "markda.editor"
}

テキストエディターに戻す

エディタータイトルの鉛筆アイコン（別のエディターで開き直す）をクリックすると、いまのファイルを VS Code 標準のエディターで開き直します。どちらも同じファイルを編集するので、いつでも行き来できます。

2. 画面の見方

タイトルバーのボタン

• 鉛筆 — 別のエディター（VS Code のテキストエディター）で開き直します。
• </> — 見たまま表示とソース表示を切り替えます。
• Export: HTML ／ Export: PDF — 文書を書き出します。そのほかの書き出しは … メニューとコマンドパレットにあります。
• 表示オプション（ツールバー右端の歯車）— テーマ、集中モード、タイプライターモードなどの表示設定。

ツールバー

左から 段落スタイル（本文・見出し 1〜6）、太字、斜体、リンク、箇条書き、番号付きリスト、引用、コードブロック、画像、表、その他の書式（取り消し線、インラインコード、タスクリスト、数式、書式の解除など）、ブロックを挿入 です。段落スタイルの欄には、カーソルのある行のスタイルが表示されます。

ステータス行

文書の下の行には、いまのモード（ライブ または ソース）、カーソルのあるセクション、語数と文字数、保存状態（VS Code 側の内容と一致していれば 同期済み）が表示されます。語数をクリックすると、行数と読了時間も表示されます。文字を選択している間は、選択範囲の数を表示します。VS Code のステータスバーにも語数が出ており、クリックすると 文書の統計を表示 が実行されます。

3. 見たまま書く

いつもどおり Markdown を入力します。行を書き終えるとすぐに整った表示に変わります。# は見出しに、**文字** は太字に、- [ ] はチェックボックスになります。Markdown の記号が見えるのは、カーソルのある行やインライン要素だけです。いま触っている箇所の記法は、いつでもそのまま確認・編集できます。

• Shift+Enter で、段落の中に Markdown の改行（ハードブレーク）を入れます。
• ** や ` などの記号は、入力すると自動で対になります。markda.editor.autoPairMarkdown で無効にできます。
• Web ページやワープロから貼り付けると、見出し・リスト・リンク・画像・表・コードを Markdown に変換します。文字だけを貼り付けたいときは プレーンテキストとして貼り付け を使います。
• Markdownとしてコピー で、選択範囲を Markdown のソースとしてコピーできます。
• インライン HTML は markda.markdown.html が有効なら描画して表示します。HTML ブロックは、markda.security.allowUnsafeHtml を有効にするまで読み取り専用です（セキュリティを参照）。

4. ツールバー・メニュー・クイック挿入

選択範囲のツールバー

文字を選択すると、その上に小さなツールバーが現れます。太字、斜体、取り消し線、インラインコード、リンク、書式の解除が使えます。

/ でクイック挿入

空の行で / を入力すると、挿入できる要素の一覧が開きます。続けて文字を入力すると絞り込めます。Enter を押すか、項目をクリックして挿入します。

挿入できるもの：見出し 1〜6、箇条書き、番号付きリスト、タスクリスト、引用、コードブロック、表、画像、数式ブロック、区切り線、目次、Front Matter、注意書き（コールアウト）、脚注。

右クリックメニュー

文書の中で右クリックすると、同じ一覧に加えて、いまの文字やブロックに対する操作が表示されます。太字、斜体、リンクを挿入、書式を解除、ブロックを上へ／下へ移動、ブロックを複製 です。

5. リンク

• ツールバーの リンク（Markda のショートカットを有効にしている場合は Ctrl+K）でリンクのダイアログを開きます。クリップボードに URL があれば自動で入力されます。タイトルの設定や、この文書・別の文書の見出しをリンク先に選ぶこともできます。
• リンクを開くには、Ctrl（macOS では Cmd）を押しながらクリックします。ほかの Markdown ファイルや見出しへのリンクは VS Code の中で開き、Web のリンクはセキュリティ設定に従って開きます。
• 修飾キーなしでクリックすると、リンクの文字と Markdown を編集できます。

6. 表

ツールバー、クイック挿入（/ → 表）、または 表を挿入 コマンドで表を挿入し、行数と列数を選びます。セルをクリックすればそのまま編集でき、画面上部に表のツールバーが現れます。

• Tab／Shift+Tab で次・前のセルに移動します。
• 行や列の見出しをドラッグして並べ替えられます。
• セルの角のハンドルをドラッグすると列の幅を変えられます。
• 列の見出しを右クリックすると、配置（左・中央・右）が順に切り替わります。
• セルの中でも太字や斜体などの書式が使えます。
• とても大きな表（markda.editor.liveTableMaxCells を超えるセル数。初期値は 600）は、動作を軽く保つため簡易的なソース編集で開きます。

7. コードブロック

ツールバーから、または ``` に続けて言語名を入力するとコードブロックになります。コードはハイライト表示されたまま、その場で編集できます。ソース表示に切り替える必要はありません。ブロックの上部には言語名（クリックで変更）と コピー ボタンがあります。コードブロック内の元に戻す・やり直しも、文書全体の履歴とつながっています。

8. 数式と図

数式（KaTeX）

インライン数式は $ で、別行立ての数式は $$ の行で囲みます。閉じた時点ですぐに描画され、処理はすべてお使いのコンピューターの中で行われます。

面積は $A = \pi r^2$ です。

$$
\int_0^1 x^2\,dx = \frac{1}{3} \label{eq:area}
$$

式 \eqref{eq:area} より……

\label{…} を付けた別行立ての数式には文書の順に番号が振られ、\ref{…} や \eqref{…} でその番号を表示できます。Markdown のソースは書き換えません。描画された数式をクリックすると、ソースを編集できます。

図（Mermaid）

```mermaid
flowchart LR
  執筆 --> 確認 --> 公開
```

Mermaid のコードブロックは図として描画されます。図をクリックするとソースが開き、編集してほかの場所をクリックすると描き直されます。数式と図の描画は markda.markdown.math、markda.markdown.diagrams で無効にできます。

9. 画像

• 画像を挿入（ツールバー・クイック挿入・コマンド）で、1 枚または複数の画像ファイルを選べます。
• クリップボードの画像を 貼り付け たり、画像ファイルを文書に ドラッグ＆ドロップ したりもできます。
• 新しい画像は markda.image.folder で指定したフォルダー（初期値は文書と同じ場所の ${currentFileNameWithoutExt}.assets）に、既存のファイルを上書きしない名前で保存され、相対パスでリンクされます。
• 画像をクリックすると、代替テキストやパスの編集、サイズの変更ができます。
• 文書の画像を監査 で、見つからない画像の参照と、文書で使われなくなった画像ファイルを確認できます。

10. ソース表示と元に戻す

タイトルバーの </>（Markda のショートカットを有効にしている場合は Ctrl+/）で、ファイル全体をそのままの Markdown として表示・編集できます。もう一度押すと見たまま表示に戻ります。

• Ctrl+Z で元に戻し、Ctrl+Y または Ctrl+Shift+Z でやり直します（macOS では Cmd）。本文・表のセル・コードブロックの履歴はひとつながりです。
• ほかのエディターや分割表示、別の拡張機能がファイルを変更すると、Markda も新しい内容に更新されます。
• 同じファイルを分割エディターで開いても（Markda と VS Code のテキストエディターを並べても）、両方の内容は同期します。

11. アウトライン・セクション・ファイル

アウトラインを表示 または ファイルを表示 を実行すると、Markda のサイドビューが開きます。

アウトライン

• 見出しの階層を表示し、いまいるセクションに印を付けます。見出しをクリックするとその位置に移動します。
• アウトラインを絞り込み で一覧を絞り込み、アウトラインの絞り込みを解除 で元に戻します。
• アウトラインのビューやコマンドパレットから、見出し名を変更、見出しレベルを上げる／下げる、セクションを上へ／下へ移動（見出しとその内容をまとめて移動）ができます。

セクションの折りたたみ

見出しの横にマウスを合わせると折りたたみのマーカーが現れ、クリックするとそのセクションを折りたためます。すべてのセクションを折りたたむ、すべてのセクションを展開、現在のセクションにフォーカス は、アウトラインのメニューとコマンドパレットにあります。折りたたみは表示だけの状態で、ファイルは変わりません。見出しへ移動すると、そのセクションを含む部分は自動で展開されます。

ファイル

• ワークスペース内の Markdown ファイルをフォルダーの階層で表示し、上部に 最近使用したファイル と ピン留め をまとめます。
• 項目の右クリックメニューから ファイルをピン留め／解除、ファイル名を変更、ファイルを削除（ごみ箱へ移動）、ファイルを表示 ができます。
• ファイルを絞り込み でツリーを絞り込めます。Markdownファイルをクイックオープン と Markdownファイル全体を検索 はワークスペース全体から、文書内を検索 はいまのファイルから探します。
• 新しいMarkdownファイル で新しい文書を作り、文書を複製 でいまの文書のコピーを作ります。

12. リンク確認・名前変更・バックリンク

• リンクの確認：編集のたびに、ローカルのファイル・画像・見出しへのリンクを確認し、切れているものを VS Code の 問題 パネルに表示します。ドキュメントのリンクを確認 でいつでも実行できます。外部の URL にはアクセスしません。自動の確認は markda.links.checkOnEdit で無効にできます。
• 名前変更時のリンク更新：VS Code や Markda のファイルビューでファイルやフォルダーの名前を変えると、それを指しているリンクと、そのファイル内のリンクを、変更前・変更後のパスとともに一覧表示します。残したいもののチェックを外して確定します。Esc を押すとリンクを更新せずに名前だけ変えます。相対パス、見出しアンカー、クエリ文字列、リンクのタイトルは保たれ、コードの中は書き換えません。更新は通常のワークスペース編集なので元に戻せます。信頼済みのワークスペースが必要で、markda.links.updateOnRename で無効にできます。
• バックリンク：折りたたまれた バックリンク ビューを開くか、バックリンクを表示 を実行すると、いまの文書にリンクしている文書が一覧できます。クリックで開けます。ほかのファイルのリンクを編集したあとは バックリンクを更新 してください。

バックリンクと名前変更時の確認は、開いているワークスペース内の Markdown・テキストファイルを最大 5,000 件まで対象にし、依存関係やビルド用のフォルダーは除外します。開いている文書の未保存の内容も反映します。HTML のリンクや、VS Code の外で行った名前変更は更新されません。

13. テンプレート

テンプレートから新規ドキュメントを作成 を実行し、議事録、プロジェクト仕様書、日誌 から選びます。新しい文書は未保存の状態で開くので、保存先は自分で決められます。markda.templates で独自のテンプレートも追加できます。{{title}} と {{date}} は作成時に置き換わります。

"markda.templates": [
  {
    "name": "週報",
    "description": "進捗・課題・次の予定",
    "body": "# {{title}}\n\n日付: {{date}}\n\n## 進捗\n\n## 課題\n\n## 次の予定\n"
  }
]

14. 集中モード・プリセット・テーマ

• フォーカスモード（F8）では、いま書いている段落以外が薄くなります。
• タイプライターモード（F9）では、カーソルの行が常に画面の中央に来ます。
• 執筆プリセットを適用 で、本文の幅や動作をワークスペース単位でまとめて設定できます。
  • Typora風 — 中央寄せの 860px、自動テーマ、すべてのライブ機能。
  • 集中して執筆 — 幅 720px の狭い本文と、タイプライターの動作。
  • 技術文書 — 表・コード・数式・図向けの幅広い 1,100px。
  • VS Codeエディターの幅全体を使う — エディターの幅いっぱいに表示。
• テーマ：markda.editor.themeMode は初期値（auto）で VS Code のライト／ダークに合わせて切り替わり、light や dark に固定することもできます。テーマを選択 で、ライト用（paper）とダーク用（midnight）のテーマや独自のテーマを選びます。テーマフォルダーを開く で開くフォルダーに置いた .css ファイルは、すべてテーマとして選べるようになります（サンプルのファイルも作成されます）。
• フォント、文字サイズ、行の高さ、段落の間隔、本文の幅はそれぞれ設定できます（設定一覧を参照）。
• スペルチェッカー、markdownlint、Vale などの診断は、重要度の色付きで文書の上に表示され、クイックフィックスから VS Code のコードアクションを実行できます。

15. 書き出し

書き出すたびに保存先を尋ねます。markda.export.defaultFolder を same にすると、文書と同じフォルダーに保存します。PDF の書き出しでブラウザーが見つからない場合は、markda.export.pdfBrowserPath に Edge・Chrome・Chromium のパスを指定してください。

外部ターゲット（例：Pandoc で Word に変換）

"markda.export.targets": [
  {
    "name": "Word (Pandoc)",
    "command": "pandoc",
    "args": ["${source}", "-o", "${destination}"],
    "extension": "docx"
  }
]

使える変数は ${source}、${destination}、${documentDir}、${documentName}、${workspaceFolder} です。コマンドはシェルを使わずに実行され、信頼済みのワークスペースでのみ動きます。出力ファイルを作らないコマンドでは extension を空欄にします。

16. キーボードショートカット

空の行での /（クイック挿入）、表の中の Tab、Shift+Enter（改行）は、設定にかかわらず使えます。

17. コマンド一覧

コマンドパレット（Ctrl+Shift+P、macOS では Cmd+Shift+P）で markda と入力すると、すべてのコマンドが表示されます。VS Code の表示言語が日本語なら、コマンド名も日本語で表示されます。

ファイルを開く・管理する

編集と書式

表示

アウトラインとセクション

リンクと画像

書き出し

18. 設定一覧

設定画面で markda と検索するか、settings.json に次のキーを書きます。ほとんどの設定はワークスペースごとに変えられます。

19. セキュリティとプライバシー

• テレメトリーなし：Markda は利用状況のデータを送信しません。
• ローカルで描画：Markdown、KaTeX の数式、Mermaid の図はお使いのコンピューターの中で描画します。文書をオンラインのサービスに送ることはありません。
• 外部のリソース（Web 上の画像など）は markda.security.allowRemoteResources に従って読み込みます。prompt（確認してから。初期値）、always、never から選べます。
• HTML は常に無害化されます。スクリプト、埋め込みフレーム、フォーム、イベントハンドラー、インラインスタイルは取り除かれます。HTML ブロックは markda.security.allowUnsafeHtml を有効にするまで読み取り専用です。有効にしても編集できるようになるだけで、無害化は省略されません。
• ワークスペースの信頼：信頼されていないワークスペースでは、ワークスペース側から指定できる画像の保存先とセキュリティ設定が制限され、外部コマンドでの書き出しと名前変更時のリンク更新は使えません。

20. 困ったときは

Markdown ファイルがテキストエディターで開く

ファイルの関連付けを構成 を実行するか、タブのメニューから一度 Reopen Editor With… → Markda を選んでください。

ショートカットが効かない

Markda のショートカットは初期状態では無効です。markda.editor.enableDefaultKeybindings を有効にするか、キーボードショートカット画面で自分で割り当ててください。

PDF の書き出しに失敗する

PDF の印刷には、インストール済みの Chromium 系ブラウザーを使います。Edge・Chrome・Chromium をインストールするか、markda.export.pdfBrowserPath に実行ファイルのパスを指定してください。

大きな表がセルではなく Markdown で表示される

セル数が markda.editor.liveTableMaxCells を超える表は、簡易的なソース編集で開きます。お使いの環境で問題なければ上限を上げてください。

Web 上の画像が表示されない

markda.security.allowRemoteResources を確認し、確認のメッセージで許可してください。信頼できる文書だけなら always にもできます。

不具合を報告する

GitHub で Issue を作成し、VS Code のバージョン、OS、再現する手順をお知らせください。