# Structure Commander v2.3.4

Structure Commander — плагин для Obsidian, который превращает Markdown-документ в управляемую структуру. Не просто «ещё одна панель заголовков», а рабочий инструмент для длинных заметок, технических заданий, конспектов, проектной документации и любых текстов, где разделы нужно двигать, сворачивать, повышать, понижать, нумеровать и экспортировать без ручной хирургии по строкам.

Если встроенная структура Obsidian показывает дерево, Structure Commander даёт с этим деревом работать: переставлять ветки, менять уровни, сворачивать нужные части, быстро показывать документ до выбранной глубины и выносить отдельные ветки в самостоятельные `.md`-файлы.

## Последнее обновление: v2.3.4

Исправлено сохранение выделения после перемещения блока вверх/вниз: повторное перемещение выделенного блока больше не теряет строки. Также восстановлено свёрнутое состояние ветки после перемещения и синхронизирована версия в `manifest.json` и README.

## Что умеет

- Перемещать Markdown-ветки вверх и вниз вместе со всеми вложенными заголовками и текстом.
- Перемещать выделенные строки вверх и вниз без потери выделения при повторных перемещениях.
- Повышать и понижать уровень текущей ветки с сохранением внутренней иерархии.
- Работать не только с заголовками, но и с обычным текстом, маркированными и нумерованными списками.
- Сворачивать и разворачивать текущую ветку.
- Показывать документ до H1, H2, H3, H4, H5 или H6.
- Показывать только реально существующие уровни заголовков в меню «Показать до».
- Полностью разворачивать документ через «Показать всё».
- Перенумеровывать заголовки и списки.
- Удалять нумерацию.
- Заменять нумерацию на emoji-цифры.
- Исправлять пропуски уровней, например H1 → H3.
- Экспортировать текущую ветку в отдельную Markdown-заметку.
- Показывать структуру в боковой панели.
- Добавлять компактную панель инструментов над редактором.
- Показывать текущие хоткеи прямо в tooltip, контекстном меню и меню тулбара.
- Быстро назначать хоткеи из настроек плагина или через ПКМ по кнопке тулбара.
- Добавлять файловые операции в контекстное меню vault.
- Открывать файл/папку в проводнике, копировать путь и копировать файл в буфер.
- Использовать режим отработки для файловых операций без фактического изменения файлов.
- Выполнять Ctrl+Z/Ctrl+Y для файловых операций плагина.

## Быстрый старт

Откройте Markdown-заметку, поставьте курсор внутрь нужного раздела и используйте хоткеи:

| Действие | Хоткей |
|---|---|
| Ветка выше | `Alt+Shift+↑` |
| Ветка ниже | `Alt+Shift+↓` |
| Повысить ветку | `Alt+Shift+←` |
| Понизить ветку | `Alt+Shift+→` |
| Свернуть ветку | `Alt+←` |
| Развернуть ветку | `Alt+→` |

Эти же действия доступны через:

- контекстное меню редактора;
- панель инструментов над редактором;
- боковую панель структуры;
- палитру команд `Ctrl+P`;
- ribbon-иконку Structure Commander.

Кнопка Structure Commander на левой панели Obsidian открывает правую боковую панель структуры.

## Основная идея

Ветка — это ближайший заголовок выше курсора и всё его содержимое до следующего заголовка того же или более высокого уровня.

Пример:

```markdown
# Раздел 1

Текст раздела.

## Подраздел 1.1

Текст подраздела.

## Подраздел 1.2

Текст подраздела.

# Раздел 2
```

Если курсор стоит внутри `Раздел 1`, команда «Ветка ниже» перенесёт весь блок `Раздел 1` вместе с `Подраздел 1.1` и `Подраздел 1.2` ниже `Раздел 2`.

Если курсор стоит внутри `Подраздел 1.1`, команда работает только с этой вложенной веткой.

## Контекстное меню редактора

ПКМ в Markdown-редакторе добавляет компактные верхнеуровневые пункты с подменю:

```text
Развернуть/свернуть ▸
   ├─ Развернуть      Alt+→
   ├─ Свернуть        Alt+←
   ├─ Показать/скрыть панель структуры
   └─ Показать/скрыть панель инструментов

Показать до ▸
   ├─ H1
   ├─ H2
   ├─ H3
   ├─ ...
   └─ Показать всё

Уровень | Перенос ▸
   ├─ Повысить        Alt+Shift+←
   ├─ Понизить        Alt+Shift+→
   ├─ Вверх           Alt+Shift+↑
   ├─ Вниз            Alt+Shift+↓
   ├─ Понизить до ▸   H2, H3, H4, ...
   └─ Повысить до ▸   H1, H2, H3, ...

Нумерация ▸
   ├─ Перенумеровать…
   ├─ Удалить нумерацию…
   ├─ Emoji-цифры…
   └─ Исправить пропуски уровней

Экспорт ветки…
```

В меню «Показать до» выводятся только уровни заголовков, которые реально есть в документе. Если в файле есть только H2 и H4, меню не будет притворяться, что H1 и H3 существуют.

В подменю «Понизить до» и «Повысить до» показываются только допустимые уровни: плагин не даст сдвинуть ветку так, чтобы вложенные заголовки вышли за пределы H1…H6.

## Контекстное меню файлов vault

ПКМ по файлу или папке vault добавляет пункт `Файл ▸`.

```text
Файл ▸
   ├─ Открыть в проводнике
   ├─ Скопировать путь
   ├─ Скопировать файл в буфер
   ├─ Отправить ▸
   ├─ Режим отработки
   ├─ Ctrl+Z — отменить файловую операцию
   └─ Ctrl+Y — повторить файловую операцию
```

Режим отработки показывает план операции, но не меняет файлы.

## Панель инструментов над редактором

Над Markdown-редактором появляется компактная панель:

```text
[↑] [↓] [←] [→] [−] [+] [Показать: H1 ▾] [H? ▾] [№] [×]
```

| Кнопка | Действие |
|---|---|
| `↑` | ветка выше |
| `↓` | ветка ниже |
| `←` | повысить ветку / строку |
| `→` | понизить ветку / строку |
| `−` | свернуть текущую ветку |
| `+` | развернуть текущую ветку |
| `Показать: Hn ▾` | выбрать глубину показа документа и выполнить «Показать всё» |
| `H? ▾` | изменить уровень текущего заголовка или всей ветки |
| `№` | открыть перенумерацию |
| ПКМ по `№` | меню: перенумеровать, удалить нумерацию, emoji-цифры, исправить уровни |
| `×` | скрыть toolbar |

Tooltip у кнопок показывает действие и текущий хоткей. Если хоткей изменён в настройках Obsidian, tooltip подтянет актуальное значение.

## Боковая панель структуры

Панель структуры похожа на штатную outline-панель Obsidian, но добавляет управляющие действия.

В панели есть:

- поиск по заголовкам;
- фильтр глубины: `До H1`, `До H2`, `До H3`, `До H4`, `До H5`, `Все`;
- счётчик `показано / всего`;
- подсветка активного заголовка по позиции курсора;
- кнопка обновления;
- кнопка закрытия панели;
- контекстное меню для каждого заголовка.

ПКМ по заголовку в панели:

```text
Перейти
Свернуть ветку
Развернуть ветку
Ветку выше
Ветку ниже
Повысить
Понизить
Экспорт ветки…
```

Уровни в панели передаются визуально: отступом, жирностью, наклоном и цветом. Подписи `H1`, `H2`, `H3` не повторяются в каждой строке.

## Экспорт ветки

Команда `Экспорт ветки…` сохраняет текущую ветку в отдельный Markdown-файл.

Окно экспорта позволяет выбрать:

- сохранить рядом с текущей заметкой;
- сохранить в указанную папку;
- спрашивать каждый раз;
- открыть файл после экспорта;
- привести корневой заголовок экспортируемой ветки к H1.

Имя файла берётся из заголовка ветки. Запрещённые символы очищаются. Если файл уже существует, добавляется суффикс `2`, `3`, `4` и так далее.

## Перенумерация

Окно перенумерации поддерживает три области:

- весь документ;
- текущая ветка;
- выделенный фрагмент.

И три цели:

- только заголовки;
- только списки;
- заголовки и списки.

Стили:

```text
1. / 1.1. / 1.1.1.
1️⃣ / 1️⃣.1️⃣ / 1️⃣.1️⃣.1️⃣
```

Перед применением показывается предпросмотр: первые 8 изменений в формате `было → станет` и общее количество изменяемых строк.

## Транзакционность и Undo

Массовые операции применяются одной транзакцией редактора:

- перемещение ветки;
- перемещение выделенного диапазона;
- повышение/понижение;
- нормализация уровней;
- перенумерация;
- удаление нумерации;
- emoji-нумерация.

`Ctrl+Z` откатывает операцию одним действием.

Перемещение реализовано через атомарную перестановку строк. Оно не должно:

- добавлять лишние пустые строки;
- склеивать заголовки;
- терять выделение строк при повторном перемещении;
- разворачивать свёрнутую ветку после перемещения;
- ломаться на первой или последней ветке;
- ломаться на файле без финального перевода строки.

## Ограничения

- Поддерживаются ATX-заголовки: `#`, `##`, `###`, `####`, `#####`, `######`.
- Markdown-заголовки H1…H6 — это предел.
- Setext-заголовки с подчёркиванием `===` / `---` не поддерживаются.
- Заголовки внутри fenced code blocks (` ``` ` или `~~~`) игнорируются.
- Глобальные хоткеи Windows / macOS / других приложений не проверяются.
- На мобильных устройствах физические хоткеи обычно бесполезны, используйте toolbar и меню.
- Файловые действия с проводником, буфером файлов и SendTo зависят от desktop-среды и возможностей Electron/ОС.

## Установка вручную

1. Закрыть Obsidian.
2. Создать папку:

```text
.obsidian/plugins/structure-commander/
```

3. Скопировать в неё:

```text
main.js
manifest.json
styles.css
```

4. Открыть Obsidian.
5. Перейти в `Настройки → Community plugins`.
6. Включить `Structure Commander`.

## Состав релиза

Для релиза GitHub должны быть приложены отдельные assets:

```text
main.js
manifest.json
styles.css
```

Не только `Source code (zip)` и не только архив. Obsidian Community Plugins проверяет именно отдельные release assets.

## Совместимость

`minAppVersion`: `1.0.0`.

Плагин не требует внешних сервисов, аккаунтов, сетевых запросов или отдельной базы данных. Работает внутри текущего vault и меняет файлы только по команде пользователя.

## License

MIT