Markdownの見出しを折りたたむ

長いMarkdownドキュメントを書いていると、全体の構成を把握しながら特定のセクションだけを編集したくなります。Neovimの折りたたみ(fold)機能を使えば、見出しごとにセクションを折りたたんで文書構造を俯瞰できます。

treesitter ベースの折りたたみを設定

Luainit.lua — treesitter ベースの fold 設定
-- treesitterの構文解析を使った折りたたみ
vim.opt.foldmethod = "expr"
vim.opt.foldexpr   = "nvim_treesitter#foldexpr()"
vim.opt.foldlevel  = 99   -- 起動時はすべて展開した状態にする
vim.opt.foldenable = true

-- Markdownファイルのみ見出しレベルで折りたたむ設定
vim.api.nvim_create_autocmd("FileType", {
  pattern = "markdown",
  callback = function()
    vim.opt_local.foldmethod = "expr"
    vim.opt_local.foldexpr   = "nvim_treesitter#foldexpr()"
    vim.opt_local.foldlevel  = 1  -- H1 だけ展開、H2以下は折りたたみ
  end,
})

折りたたみの基本操作

キー動作
zaカーソル位置の折りたたみをトグル(開閉)
zoカーソル位置の折りたたみを開く(open)
zcカーソル位置の折りたたみを閉じる(close)
zRすべての折りたたみを開く(全展開)
zMすべての折りたたみを閉じる(全折りたたみ)
zOカーソル位置の折りたたみを再帰的にすべて開く
zCカーソル位置の折りたたみを再帰的にすべて閉じる
zj次の折りたたみへ移動
zk前の折りたたみへ移動
[z現在の折りたたみブロックの先頭へ移動
]z現在の折りたたみブロックの末尾へ移動
💡
使い方のコツ まず zM で全体を折りたたんで構成を確認し、編集したいセクションで za または zo で開くという使い方が効率的です。長いドキュメントの全体像把握に最適なワークフローです。

aerial.nvim / outline.nvim でアウトラインビュー

aerial.nvim は文書の見出し構造をサイドパネルに表示するプラグインです。Markdown の見出し(H1〜H6)だけでなく、LuaやPythonなどのコードファイルでは関数・クラスの一覧もアウトラインとして表示されます。

Luaplugins/aerial.lua
{
  "stevearc/aerial.nvim",
  dependencies = { "nvim-treesitter/nvim-treesitter", "nvim-tree/nvim-web-devicons" },
  keys = {
    { "<leader>ao", "<cmd>AerialToggle!<cr>", desc = "Outline Toggle" },
  },
  opts = {
    backends = { "treesitter", "lsp", "markdown" },
    layout = {
      max_width = { 40, 0.2 },
      default_direction = "right",  -- 右側に表示
    },
    filter_kind = false,  -- すべての種類を表示
    highlight_on_hover = true,  -- ホバー時にハイライト
    autojump = false,
  },
}

aerial の操作

キー動作
<leader>aoアウトラインパネルをトグル
Enter選択した見出しの位置へジャンプ
{前の見出しへジャンプ
}次の見出しへジャンプ
[[前の同レベル見出しへ
]]次の同レベル見出しへ
q / <Esc>アウトラインパネルを閉じる
ℹ️
outline.nvim について outline.nvim(hedyhli/outline.nvim)は aerial.nvim の軽量な代替プラグインです。よりシンプルな設定で同様のアウトライン表示ができます。機能が少ない分、動作が速く設定が簡単という特徴があります。

Telescope でMarkdown見出しジャンプ

Telescope の treesitter ピッカーを使うと、Markdownの見出しを一覧から選んで瞬時にジャンプできます。アウトラインパネルを常時表示したくない場合はこちらの方法が便利です。

Telescope で見出しジャンプ
:Telescope treesitter  " treesitter シンボル一覧
:Telescope lsp_document_symbols  " LSP シンボル(LSP設定時)
 
# キーマップに登録する場合
<leader>fs → :Telescope treesitter
LuaMarkdown 見出しジャンプのキーマップ
-- Markdownファイル内でのみ有効な見出しジャンプ
vim.api.nvim_create_autocmd("FileType", {
  pattern = "markdown",
  callback = function()
    vim.keymap.set("n", "<leader>fh",
      "<cmd>Telescope treesitter<cr>",
      { buffer = true, desc = "Jump to Heading" })
  end,
})

TOC(目次)の自動生成

markdown-toc を使うと、Markdownファイルの見出しから目次を自動生成できます。コマンドラインツールとして使うか、Neovimプラグイン経由で使います。

markdown-toc のインストールと使い方
$ npm install -g markdown-toc
 
# ファイルにTOCを挿入(<!-- toc --> の位置に生成)
$ markdown-toc -i README.md
 
# Neovim内から実行
:!markdown-toc -i %

Markdownファイルに <!-- toc --> と書いておくと、その位置に目次が自動挿入されます。更新も同じコマンドで上書きできます。

MarkdownTOC プレースホルダーの書き方
<!-- toc -->
<!-- tocstop -->

# はじめに
...
## 概要
...
## インストール
...

階層的なメモ管理方法

Neovimをメモツールとして使う場合、ディレクトリ構造とMarkdownファイルを組み合わせた階層的な管理が効果的です。

推奨ディレクトリ構造
notes/
├── daily/
│ ├── 2026-06-01.md
│ └── 2026-06-06.md
├── projects/
│ ├── project-a/
│ │ ├── index.md ← プロジェクト概要
│ │ └── tasks.md ← タスク一覧
│ └── project-b/
├── ideas/ ← アイデアメモ
└── references/ ← 参考資料・メモ

この構造にしておくと、Telescope の live_grep でキーワード検索したとき、すべてのMarkdownファイルを横断して検索できます。Obsidian のvault をこの構造に合わせると、obsidian.nvim との連携もスムーズです。

タスクリストとしての使い方

MarkdownのチェックボックスをNeovimで快適に操作することで、タスク管理ツールとしても使えます。

Markdownタスクリストの記法
# 今日のタスク

- [ ] 未完了のタスク
- [x] 完了したタスク
- [ ] 期限: 2026-06-10 — 重要なタスク

## プロジェクトA
- [ ] 要件定義
  - [x] ヒアリング
  - [ ] ドキュメント作成
- [ ] 実装
- [ ] レビュー

チェックボックスをワンキーでトグルする設定

Luaチェックボックストグルのキーマップ
-- Markdownのチェックボックスを <leader>tc でトグル
vim.api.nvim_create_autocmd("FileType", {
  pattern = "markdown",
  callback = function()
    vim.keymap.set("n", "<leader>tc", function()
      local line = vim.api.nvim_get_current_line()
      if line:match("^%s*%- %[%]") then
        line = line:gsub("- %[%]", "- [x]", 1)
      elseif line:match("^%s*%- %[x%]") then
        line = line:gsub("- %[x%]", "- [ ]", 1)
      end
      vim.api.nvim_set_current_line(line)
    end, { buffer = true, desc = "Toggle Checkbox" })
  end,
})

Zettelkasten / Second Brain としての活用

Zettelkasten(ツェッテルカステン)は、メモを小さな単位で作成し、相互リンクでつないでいく知識管理手法です。Neovimと obsidian.nvim を組み合わせることで、ObsidianのUIなしにNeovimだけで完全なZettelkastenを構築できます。

📌
Zettelkasten の基本原則 1. Atomic Notes: 1つのメモに1つのアイデアだけを書く
2. リンク: [[ノート名]] で他のメモと関連付ける
3. 永続的なID: タイムスタンプや連番でファイル名を固定する
4. インデックス: 入口となるインデックスノートを作成する
Luaobsidian.nvim — Zettelkasten 向け設定
opts = {
  workspaces = {
    { name = "zettelkasten", path = "~/Notes/Zettel" }
  },
  -- タイムスタンプIDでノートを作成
  note_id_func = function(title)
    local suffix = ""
    if title then
      suffix = title:gsub(" ", "-"):lower()
    else
      -- タイトルがない場合はタイムスタンプを使用
      suffix = tostring(os.time())
    end
    return os.date("%Y%m%d%H%M") .. "-" .. suffix
  end,
  -- [[リンク]] の補完を有効化
  completion = { nvim_cmp = true },
}

複数ファイルにまたがるアウトライン管理

大きなプロジェクトや書籍を書くとき、複数のMarkdownファイルを1つのアウトラインとしてまとめたい場合があります。以下のアプローチが有効です。

インデックスファイル方式

index.md にすべての章・セクションへのリンクを書いたインデックスファイルを作成します。obsidian.nvim や vim-markdown の [[リンク]] 機能で各ファイルにジャンプします。

Markdownbook/index.md — 書籍のアウトライン例
# 書籍タイトル

## 目次

- [[01-はじめに]]
- [[02-第一章]]
  - [[02-01-背景]]
  - [[02-02-理論]]
- [[03-第二章]]
- [[04-おわりに]]

## 執筆メモ
- [ ] 第一章の見直し
- [ ] 図版の挿入
- [x] プロローグ完成

Telescope live_grep で横断検索

プロジェクトのルートディレクトリで :Telescope live_grep を実行すると、すべてのMarkdownファイルを横断してキーワード検索できます。分割されたファイル間の内容を横断的に把握するのに非常に便利です。

キーマップ一覧

折りたたみ操作

キー動作
za折りたたみをトグル(開閉)
zo / zc折りたたみを開く / 閉じる
zR / zMすべて展開 / すべて折りたたみ
zj / zk次 / 前の折りたたみへ移動

アウトライン・見出しジャンプ

キー(推奨設定)動作
<leader>aoaerial.nvim のアウトラインパネルをトグル
<leader>fhTelescope で見出しジャンプ
{ / }aerial 内で前 / 次の見出しへ
[[ / ]]前 / 次の同レベル見出しへ

タスク管理

キー(推奨設定)動作
<leader>tcチェックボックスをトグル
<leader>on新規 Obsidian ノートを作成
<leader>osObsidian ノートを検索
💡
アウトライナーとして使うためのまとめ Neovimをアウトライナーとして最大限活用するには、折りたたみ + aerial.nvim + obsidian.nvim の3本柱が揃えば十分です。折りたたみで俯瞰し、aerialでジャンプし、obsidianでリンクでつなぐ。このワークフローが定着すると、専用アウトライナーアプリが不要になります。