Назад к статьям
Статья

Мы написали CMS-бэкенд на .NET для markdown и отказались от него в пользу SSR на Nuxt

Долгое время этот блог обслуживал бэкенд, который мы написали сами: 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 как часть истории и на случай, если появятся новые идеи.

Предыстория — почему мы вообще выбрали такой стек — в статье Выбор стека пет-проекта для небольшой команды.