📨 tg2md

English version → README_EN.md

Консольный инструмент для конвертации экспорта Telegram-канала в Markdown-статьи.

Превращает result.json из экспорта Telegram в отдельные .md файлы, готовые для Astro или любого другого SSG. Удобно для переноса контента в Obsidian, Logseq и другие Markdown-first инструменты.

---

⚡ Быстрый старт

npx tg2md <путь-к-result.json>

# С указанием выходной папки:
npx tg2md ./ChatExport/result.json -o ./src/content/blog

# Перезаписать существующие файлы:
npx tg2md ./ChatExport/result.json --rewrite

# Полная очистка выходной папки перед конвертацией:
npx tg2md ./ChatExport/result.json --clean

---

📦 Установка

Можно запускать без установки через npx, или установить глобально:

npm install -g tg2md

---

📥 Как получить result.json

1. Откройте Telegram Desktop (не Telegram для macOS)
2. Зайдите в нужный канал
3. Нажмите ⋮ → Экспорт истории чата
4. Выберите формат: JSON
5. Включите загрузку фото
6. Нажмите Экспортировать

В папке экспорта появится файл result.json и папка photos/.

---

🔄 Что происходит при конвертации

Каждый пост конвертируется в отдельный .md файл

Имя файла формируется автоматически:

YYYY-MM-DD-транслит-заголовка.md

Например: 2026-02-22-vsyo-chto-nuzhno-znat-pro-litij-ionnye-akkumulyatory.md

Frontmatter в стиле Astro

---
title: 'Всё, что нужно знать про литий-ионные аккумуляторы'
description: 'Я сейчас катаюсь в горах за полярным кругом и тут холодно...'
pubDate: 'Feb 22 2026'
heroImage: '/images/photo_278@22-02-2026.jpg'
---

Поле	Откуда берётся
title	Первый bold-текст поста. Если нет — первое предложение
description	Первый абзац текста (без заголовка), обрезается до ~160 символов
pubDate	Дата публикации поста
heroImage	Путь к фото (только если пост содержит фото)

Форматирование текста

Telegram	Markdown
Жирный	**жирный**
Курсив	*курсив*
Зачёркнутый	~~зачёркнутый~~
Подчёркнутый	<u>подчёркнутый</u>
Спойлер	<span class="spoiler">текст</span>
Цитата	> текст
Код	`код`
Блок кода	```код```
Ссылка	[текст](url)
Команда /start	`/start`
Кастомный эмодзи 🤌	Стандартный эмодзи (fallback)

🖼 Фото

Фото копируются в images/ внутри выходной директории. Путь в frontmatter: /images/имя_файла.jpg

Важно: фотографии должны быть в папке экспорта. При экспорте убедитесь, что включен экспорт фото.

🚫 Что игнорируется

• Репосты (forwarded) — не конвертируются
• Видео — текст сохраняется, файл не копируется
• Реакции — не включаются
• Ответы (reply_to) — контекст ответа не добавляется

---

📁 Структура выходной папки

output/
├── images/
│   ├── photo_272@06-02-2026_22-06-23.jpg
│   └── photo_273@10-02-2026_13-32-02.jpg
├── 2026-02-02-vstrechajte-gejmifikaciyu-v-kommentah.md
├── 2026-02-04-ya-lyublyu-halyavu.md
└── 2026-02-22-pro-akkumulyatory.md

---

🚀 Интеграция с Astro

Скопируйте содержимое output/ в проект Astro:

src/content/blog/    ← md-файлы
public/images/       ← изображения

Убедитесь, что в src/content/config.ts описана коллекция blog:

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    heroImage: z.string().optional(),
  }),
});

---

🛠 Опции CLI

Флаг	Описание	По умолчанию
--output, -o	Выходная папка	./output
--rewrite, -r	Перезаписать существующие файлы	—
--clean, -c	Полностью очистить выходную папку перед конвертацией	—
--help, -h	Показать справку	—

Примечание: по умолчанию существующие файлы не перезаписываются — они пропускаются, а в конце выводится подсказка.

---

🧪 Тесты

npx vitest run         # один раз
npx vitest             # watch-режим

Подробнее о тестах → src/__tests__/README.md

---

🏗 Структура кода

src/
├── index.ts          # Точка входа CLI
├── cli.ts            # CLI-логика: parseArgs, uniqueFilename, main
├── parser.ts         # Парсинг JSON-экспорта
├── converter.ts      # Сборка Markdown-файла
├── extractors.ts     # Извлечение заголовка и описания
├── formatting.ts     # Форматирование entity → Markdown
├── slugify.ts        # Транслитерация и slug
└── types.ts          # Типы данных

---

👤 Автор

Evgeny Cherkasov — Telegram-канал 📬

📄 Лицензия

MIT