Версия источника: 613500afd8eca5143b4094f6f5cd48e67844f8ff
Синхронизировано: 2026-11-11T03:48:23.836Z
Источник: https://github.com/sergey-from-riders/vibecoding-base/tree/613500afd8eca5143b4094f6f5cd48e67844f8ff

<a id="architecture-markdown-publishing"></a>

# Публикации из Markdown: GitHub, даты, Redis и выгрузка

## Коротко

Markdown-файл может быть полноценной публикацией: с датой, разделом, тегами, историей правок и устойчивым адресом. Файл хранит содержание, сайт отвечает за представление, а кеш ускоряет чтение. Новые материалы можно показывать первыми без отдельной базы статей.

## Плохо

```text
Открытие статьи → запрос GitHub → разбор Markdown.
Новые файлы определяются по времени копирования на сервер.
После синхронизации все статьи становятся «свежими».
Выгрузка читает main заново и отличается от открытой страницы.
```

## Хорошо

```text
GitHub main → конкретный commit → проверка → целый снимок.
Опубликовано: 2026-11-09; изменено: 2026-11-11.
Новые материалы сортируются по published_at, а не по имени файла.
Страница и выгрузка используют одну версию из кеша.
```

## Почему

Текстовый формат не мешает хранить структурированные данные. Метаданные в начале файла позволяют собирать каталог так же, как из записей базы. Git даёт историю и ревью, но не должен становиться сетевой зависимостью каждого перехода читателя.

Раздельные даты не позволяют выдать старую статью за новую после переноса файлов. Проверенный снимок защищает сайт от незавершённого обновления: разделы, ссылки, примеры и изображения относятся к одному коммиту.

## Когда применять

Справочники, документация и статьи, которые меняются через редакторское ревью и PR. Для комментариев, пользовательских заказов и частых совместных правок подходит отдельное хранилище с нужными правами и транзакциями. Этот материал не предлагает заменять любую CMS набором файлов.

Redis здесь является восстанавливаемым кешем. Если в другом проекте Redis выбран основным хранилищем, нужны отдельные гарантии сохранности. Публичные материалы можно передавать браузеру целиком при небольшом объёме; огромную или приватную базу так загружать не следует.

## Как проверить

- Опубликуйте тестовый материал: он появляется выше старых по дате публикации.
- Измените старую статью: её дата публикации остаётся прежней.
- Повторите синхронизацию: даты проверки и публикации не меняются.
- Сопоставьте версию открытой страницы и Markdown-выгрузки.
- Отключите GitHub и Redis в тестовой среде: доступна последняя исправная дисковая версия.
- Добавьте ошибочный Markdown: рабочий снимок не заменяется.

## Человек

Определяет содержание, дату первой публикации и основания рекомендаций. Проверяет PR и обновляет дату содержательной проверки только после реального пересмотра. Не ставит сегодняшнюю дату старому материалу ради позиции в выдаче.

## Агент

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

## Пример применения

**1. Один материал — один файл.**

В начале файла находится front matter — небольшой блок метаданных. В этом реестре значения записываются в JSON-синтаксисе внутри ограниченного YAML: строки в кавычках, массивы в квадратных скобках. Это правило нашего парсера, а не ограничение Markdown вообще.

```yaml
published_at: "2026-11-09"
reviewed_at: "2026-11-11"
section: "architecture"
tags: ["Markdown", "публикации"]
```

Это фрагмент метаданных, не полный файл правила. Для публикации также нужны стабильный ID, заголовок, уровень, первоисточники и обязательные разделы. Имя файла отвечает за понятный путь, а не за хронологию.

**2. Четыре даты решают разные задачи.**

«Опубликовано» — подтверждённая дата первого выпуска материала. Она не меняется при редактировании. «Изменено» — дата изменения файла; в справочнике она берётся из Git. «Проверено» — дата содержательного пересмотра автором. «Синхронизировано» — время получения снимка сайтом, одно на всю версию. Копирование файла и перезапуск Redis не меняют дату публикации.

Для исторического материала без подтверждённой даты не подставляют сегодняшний день: дата остаётся неизвестной. Такой материал доступен, но не попадает в свежие публикации. Даты представлены календарными значениями YYYY-MM-DD; время синхронизации хранится с часовым поясом.

**3. Сортировка отделена от хранения.**

«Сначала новые» использует published_at по убыванию, «Сначала старые» — по возрастанию. «Недавно изменённые» использует дату изменения. Неизвестная дата публикации всегда идёт после известных. При равенстве используется редакционный порядок и стабильный ID: результат не прыгает между открытиями. Тот же алгоритм нужен серверу, браузеру и оглавлению выгрузки.

**4. Обновляется вся версия.**

Процесс синхронизации проверяет main, фиксирует SHA коммита и читает все файлы именно из него. До публикации проверяются уникальность ID, связи, даты, примеры и изображения. Затем целый снимок помещается в Redis и сохраняется на диске. Сохраняются текущая и предыдущая исправные версии. Ошибка сети или материала оставляет рабочую версию доступной.

В eval.su проверка main запускается каждые 10 минут. Во время чтения страницы не запрашивают GitHub. У открытой вкладки есть собственная версия: уведомление о новой версии или обновление снимка не должно смешивать старую страницу с новой выгрузкой.

**5. Кеш и экспорт восстанавливаемы.**

В Redis хранятся готовые данные для чтения, включая проверенные иллюстрации; диск позволяет пережить недоступность Redis. Redis persistence полезна, но не заменяет исходники и проверенный сценарий восстановления. При отсутствии любой исправной версии сайт сообщает временную недоступность, а не показывает пустой справочник.

Выгрузка содержит Markdown, оглавление для подборки, даты, SHA источника и ссылки на исходные файлы. Ссылки на изображения привязаны к тому же коммиту. Если старая версия больше не хранится, сайт просит обновить страницу вместо молчаливой выгрузки другой редакции.

**6. Проверка важнее надписи.**

«Сохранено в GitHub», «синхронизировано» и «проверено автором» — разные утверждения. При выпуске проверяются реальный адрес статьи, новая позиция в выдаче и скачанный файл. Успешная сборка сама по себе ещё не доказывает публикацию.

## Источники

- [Front matter](https://gohugo.io/content-management/front-matter/)
- [ByDate](https://gohugo.io/methods/pages/bydate/)
- [Redis persistence | Docs](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/)

Уровень: Зависит от задачи. Опубликовано: 2026-11-11. Проверено: 2026-11-11. Изменено: 2026-11-11.

[Исходный файл](https://github.com/sergey-from-riders/vibecoding-base/blob/613500afd8eca5143b4094f6f5cd48e67844f8ff/registry/standards/content/markdown/rules/markdown-publishing.md)