# Спецификация `export_docs.py`

## Цель

Публикация аналитических Markdown-статей из рабочих каталогов проекта (`docs/` и др.) в wiki-репозиторий (`*.wiki.git`) с:

- размещением в указанной папке wiki (`--folder`);
- сохранением структуры подкаталогов по маске;
- конвертацией локальных ссылок между выгружаемыми `.md`-файлами.

## CLI

```bash
python export_docs.py push \
  --files <glob> [<glob> ...] \
  -s <path-to-src-or-config> \
  --folder <wiki/subfolder> \
  [--wiki-url <repo.wiki.git>] [--remote origin] \
  [--work-dir <path>] [-o <path>] [--branch main] \
  [-m "commit message"] [--dry-run]
```

## Параметры

- `--files` (обяз.): одна или несколько glob-масок.
  - Экспортируются только `.md`.
  - Если маска указывает на каталог — берутся `**/*.md`.
  - Пример: `./docs/*.md`, `./docs/**/*.md`, `./reports`.
- `-s/--src` или `-c/--config` (опц.): путь к конфигурации/`src` только для определения wiki URL по remote (аналогично `export_1c_help.py`).
  - Если не указаны, анализируется текущая папка: берётся git remote текущей папки и из неё выводится `*.wiki.git`.
- `--folder` (опц., по умолчанию `docs`): папка назначения в wiki, например `docs` или `migration/docs`.
- `--wiki-url` (опц.): явный wiki URL; если не указан, выводится из `git remote` источника.
- `--dry-run`: сборка + подготовка clone, без `git push`.

## Правила размещения файлов

1. Для каждой маски определяется статический префикс (часть до wildcard).
2. Для каждого совпавшего `.md` считается относительный путь от этого префикса.
3. В wiki файл размещается как:
   - `<folder>/<relative-path-from-pattern-root>`.

Примеры:

- `--files ./docs/*.md --folder docs`
  - `docs/a.md` → `docs/a.md`
- `--files ./docs/**/*.md --folder migration/docs`
  - `docs/plan.md` → `migration/docs/plan.md`
  - `docs/phases/p1.md` → `migration/docs/phases/p1.md`

## Конвертация ссылок

Для Markdown-ссылок вида `[text](target)` и `![alt](target)`:

- внешние URL (`http(s)`, `mailto`, `ftp`), якоря `#...`, абсолютные `/...` — без изменений;
- относительные ссылки на выгружаемые `.md` пересчитываются на новый относительный путь между целевыми файлами в wiki;
- ссылки на невыгружаемые файлы остаются как есть.

Цель: сохранить ссылочность внутри набора опубликованных статей.

## Управление удалениями (без потери чужих wiki-страниц)

Используется отдельный manifest для `export_docs` в корне wiki clone:

- `manifest.export_docs.<hash(folder)>.json`.

При следующем запуске для того же `--folder`:

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

## Ограничения текущей версии

- Автоматически обрабатываются только `.md` как источники выгрузки.
- Вложения (картинки/файлы), на которые есть локальные ссылки в `[](...)` / `![](...)`, **копируются** в wiki вместе со статьями (с сохранением структуры каталогов относительно статического префикса маски).
- Rewrite поддерживает как:
  - inline-ссылки/картинки: `[](...)` и `![](...)`;
  - reference-style определения: `[id]: target` (то есть ссылки вида `[text][id]` остаются рабочими, т.к. переопределения переписываются).