Источником материала остаётся чистый Markdown. Публикация использует существующие Python-рендереры и publish.sh; Astro добавляет современные входные страницы, но не заменяет проверенный контентный pipeline.

Публикационный pipeline HomeLab Journal

Ручная публикация

posts/article.md
      |
      v
render_post.py
      |
      +--> posts/article.html
      +--> posts/index.json
      +--> search / RSS / sitemap
      |
      v
publish.sh --> Git --> service checks

Базовая последовательность:

cd /opt/homelab-site
python3 render_post.py posts/article.md posts/article.html
python3 update_posts_index.py
./publish.sh

Системные Python-зависимости на Ubuntu устанавливаются через apt. Для Markdown используется python3-markdown; случайный pip install в системное окружение не нужен.

Что делает publish.sh

  1. Захватывает общую блокировку публикации через flock.
  2. Проверяет и создаёт недостающие обложки.
  3. Перерендеривает Markdown-материалы штатными рендерами.
  4. Обновляет JSON-индексы проектов, постов, заметок и переводов.
  5. Собирает поиск, RSS, общую карту страниц и sitemap.
  6. Собирает Astro entrypoints, не удаляя существующие HTML-материалы.
  7. Фиксирует изменения в Git.
  8. Перезапускает приложение и делает reload nginx.

Автоматические издатели

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

RSS / source queue
       |
       v
select --> deduplicate --> generate --> validate
                                      |
                                      v
                              atomic Markdown write
                                      |
                                      v
                                 publish.sh

Источник отмечается обработанным только после успешной сборки и проверки результата. Ошибка модели или RSS не должна оставлять половину статьи и не должна блокировать следующую попытку.

Что проверять после публикации

  • создан Markdown и соответствующий HTML;
  • материал появился в нужном JSON-индексе;
  • карточка видна в разделе и, если нужно, на главной;
  • поиск, RSS и sitemap содержат новый URL;
  • git status не показывает неожиданных файлов;
  • homelab-app и nginx активны;
  • основные страницы возвращают успешный HTTP-ответ.

Чего нельзя делать

  • вызывать publish.sh внутри синхронного веб-запроса;
  • редактировать только сгенерированный HTML;
  • запускать сервис от root, если он рассчитан на пользователя ubuntu;
  • помещать в Markdown HTML-мусор и незакрытые code fences;
  • запускать два издателя без общей блокировки;
  • считать Git заменой резервной копии секретов и данных.