📨 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/[email protected]'
---

| Поле | Откуда берётся | |------|---------------| | 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