Долгое время этот блог обслуживал бэкенд, который мы написали сами: Laraue.CmsBackend — библиотека на .NET, которая превращает markdown-файлы в API с запросами, и небольшой .NET-хост вокруг неё. За каждым списком, статьёй и тегом фронтенд на Nuxt ходил в этот API. Это работало, но идея была плохая. Недавно мы удалили хост и перенесли markdown-файлы в приложение на Nuxt: теперь оно читает их само и рендерит всё через SSR. Эта статья о том, почему мы так сделали.
Если вы собираетесь спрятать markdown за отдельным API, сначала прочитайте её.
Что мы построили и зачем
Цель была разумной: хранить контент в Git в виде markdown-файлов отдельно от фронтенда и получать его через API — с фильтрацией по тегам, сортировкой по дате и пагинацией, без базы данных. Полноценные CMS казались тяжёлыми, а куча markdown внутри фронтенда — смешением ответственности. Так появился третий вариант: типизированная библиотека на .NET, которая читает файлы с frontmatter, и хост с несколькими эндпоинтами — лента, категории, теги, статьи, проекты, RSS, карта сайта и генератор превью-картинок.
Первая версия блога была без SSR, и Google индексировал новые посты неделями. Мы включили SSR, и с тех пор на каждый запрос страницы сервер Nuxt ходил в API, а в ответ отдавал готовый HTML. Поисковики остались довольны. А мы — нет, и по другой причине.
Во что это обошлось: фронтенд и бэкенд никогда не были синхронизированы
Блог — это в основном фронтенд. Почти любая мелкая правка затрагивала обе стороны, потому что API решал, что странице вообще известно:
- Даты не на том языке. Даты форматировал сам бэкенд — выражением прямо в запросе:
format(createdAt, "dd MMM yyyy"). На русских страницах было написано «26 Jun 2026». Чтобы это исправить, пришлось менять контракт бэкенда, а не страницу. - Проект в виде слага. Статья знала связанные проекты только по имени файла, поэтому в боковой панели стояло «boards» с ракетой рядом. Чтобы показать нормальное название, нужно было новое поле в бэкенде, новый запрос в хосте и согласованная правка фронтенда.
- Чего не умел markdown-рендерер. У нашего рендерера были свои представления о прекрасном: он не экранировал амперсанд, терял обратные слеши в блоках кода и начинал нумерованный список заново после блока кода. Каждая такая проблема была багом в отдельном проекте, который нужно было починить, выпустить и задеплоить.
- DTO на всё. Каждому экрану нужны были DTO для списка и для страницы с подробностями, со списком свойств в виде строк. Чтобы добавить «предыдущую и следующую статью» или счётчик тегов, приходилось править C#-классы, строковые выражения и TypeScript-интерфейсы и вручную следить, чтобы они совпадали.
- Два деплоя ради одной правки. Изменение в библиотеке — это выпуск NuGet-пакета, затем деплой хоста, затем деплой фронтенда, строго в таком порядке. Перепутал порядок — страница сломана до следующего деплоя.
- Перезапуск, чтобы увидеть правку. Хост читал markdown-файлы один раз при старте, поэтому любая правка — даже опечатка — появлялась только после перезапуска контейнера бэкенда. Всё остальное во фронтенде dev-сервер подхватывает сразу, и только контент требовал ручного перезапуска.
- Функции не на своих местах. Время чтения считал бэкенд по длине отрендеренного HTML, хлебные крошки фронтенд угадывал по сегментам маршрута, карта сайта лежала в третьем месте, а генератор превью был отдельным кодом на C#.
Ничего из этого не сложно. Но вместе выходило так, что сделать блог чуть лучше за вечер никогда не получалось одной правкой. Каждый раз это был маленький согласованный релиз двух репозиториев, а это время мы предпочли бы потратить на статьи. Когда правка обходится так дорого, их делают меньше.
Поворот с SSR
С SSR разделение стало только хуже. При серверном рендеринге страницу и её данные как раз удобнее держать в одном процессе: сервер рендерит страницу, и контент нужен ему прямо сейчас. А с отдельным API сервер Nuxt на каждый запрос ходил по HTTP в другой сервис за контентом, который мог бы лежать файлом на его же диске. Мы платили за архитектуру, которую SSR потом сделал бессмысленной.
Что мы сделали вместо этого
Мы перенесли markdown-файлы в репозиторий Nuxt — в content/blog/en/… и content/blog/ru/… — и написали небольшой каталог на TypeScript: он разбирает frontmatter, рендерит markdown и отдаёт то же, что отдавал старый API, — списки, теги, соседние страницы, категории. Сервер читает файлы один раз при старте. Страницы получают данные от того же сервера Nuxt, без сетевых вызовов во время рендеринга. RSS, карта сайта и превью-картинки — маршруты того же приложения.
Каталог и его маршруты — около 700 строк на TypeScript. Хост, который они заменили, — около 870 строк на C#, не считая библиотеки за ним. Мы сохранили все публичные URL, сравнили обход старого и нового сайта (статус, canonical, hreflang, og:image) и не потеряли ни одной страницы.
Если вы тоже храните контент в markdown, вам могут пригодиться два небольших инструмента с этого сайта: переводчик Markdown для перевода .md файлов и конвертер Markdown в HTML, чтобы проверить, как отображается текст.
Результаты
- Один деплой. Один репозиторий, одна сборка, один контейнер вместо двух сервисов и библиотеки.
- Правки видны сразу. При разработке изменённый markdown-файл появляется после обновления страницы, как любое другое изменение, и ничего перезапускать не нужно.
- Каждое изменение — в одном месте. Даты на нужном языке, подписи тегов со счётчиками, кнопки «предыдущая» и «следующая» на каждой странице, короткие названия связанных проектов, новые заголовки для поисковой выдачи — каждая такая правка делалась в одном месте, а некоторые заняли минуты.
- Контент покрыт тестами. Тест читает настоящие файлы и роняет сборку, если нет перевода, есть битая ссылка или ошибка во frontmatter. При первом же запуске он нашёл в русской статье ссылку, которая вела на английскую страницу.
- Читатели ничего не заметили. Страницы статей и проектов, RSS, карта сайта и адреса превью-картинок остались прежними.
- Меньше того, что нужно запускать. Нет отдельного хоста, его health-check'а, метрик и маршрутов в nginx.
От чего мы отказались
Это компромисс, и у него есть цена. Контент теперь часть фронтенда, поэтому исправление опечатки в статье означает деплой всего сайта: сборку, тесты и новый контейнер для каждой страницы, а не просто перезапуск небольшого сервиса, который отдаёт текст. Старая схема позволяла менять контент, вообще не трогая фронтенд.
Для нас это приемлемо: деплой автоматический, занимает минуты, а статей мы публикуем несколько в месяц. Но на сайте, где контент правят часто или где редакторы не разработчики, это было бы болезненно.
Когда отдельный бэкенд для контента всё же оправдан
Мы не считаем, что headless API для контента — всегда ошибка. Он подходит, когда:
- Контент редактируют не разработчики, и им нужна админка, а не Git.
- Один контент использует несколько клиентов — сайт, мобильное приложение, рассылка — и API служит контрактом между ними.
- У контента свой цикл: публикация, черновики и отложенный выпуск, не связанные с деплоем фронтенда.
К нам ничего из этого не относилось: небольшая команда, один сайт, контент в Git. Если у вас похожая ситуация и вы используете Nuxt, сначала посмотрите на Nuxt Content — та же идея, но поддерживают её другие люди. Свой каталог мы написали, потому что потребности у нас были небольшие, и мы хотели, чтобы так и оставалось.
Выводы
- За отдельный API платишь при каждом изменении, а не один раз. Оценивать эту цену стоит по тому, сколько правок затрагивают обе стороны.
- Если страница и её данные — один продукт, держите их в одной единице деплоя.
- С SSR аргументы за отдельный сервис контента слабеют: сервер, который рендерит страницу, может сам прочитать файлы.
- Если честно, библиотека нам больше не нравится. Мы перестали её развивать, но не удалили: она остаётся на GitHub как часть истории и на случай, если появятся новые идеи.
Предыстория — почему мы вообще выбрали такой стек — в статье Выбор стека пет-проекта для небольшой команды.