Blueprint: Obsidian as CMS

Паттерн для использования Obsidian vault как системы управления контентом для веб-сайтов. Контент пишется в markdown, YAML frontmatter управляет поведением (slug, тип вывода, доступ), sync-скрипт трансформирует в web-ready форматы. Vault — единственный источник правды.

Как применить

1. Открой coding agent в директории проекта сайта (не vault)
2. Покажи ему этот Blueprint: "Мне нужен CMS на базе Obsidian, собери по этому Blueprint"
3. Агент задаст вопросы — в том числе "где твой vault?" (абсолютный путь)
4. Ответь про стек, типы контента, деплой
5. Агент напишет sync-скрипт, настроит pipeline, проверит на реальных файлах vault

Контекст: одна сессия из code project. Агент читает vault по абсолютному пути, пишет код в проекте. Vault-работа минимальна (создать папки, добавить YAML в файлы) — агент делает это через файловый доступ.

Когда использовать

• Сайт с текстовым контентом (блог, документация, гайды, курсы, лендинги)
• Контент-менеджер уже работает в Obsidian и не хочет переключаться в CMS
• Нужна быстрая итерация: отредактировал .md → запустил sync → на сайте
• Хочется использовать Obsidian-фичи (wikilinks, graph view, templates) для работы с контентом

Ключевая идея

Obsidian — редактор. YAML frontmatter — конфигурация. Sync-скрипт — движок. Сайт — вывод.

Человек:

• Пишет контент в markdown
• Управляет поведением через YAML frontmatter (slug, тип, доступ)
• Организует контент по папкам (папка = тип контента)
• Запускает публикацию ("деплой" или "обнови сайт")

AI:

• Пишет и поддерживает sync-скрипт
• Парсит YAML и трансформирует markdown в нужный формат
• Генерирует манифест контента
• Деплоит

Архитектура

Obsidian Vault (source of truth)
    │
    ├── Папка A/         .md файлы с YAML frontmatter
    ├── Папка B/         .md файлы с YAML frontmatter
    ├── Папка C/         .md файлы с YAML frontmatter
    │
    └──── Sync-скрипт ─────┐
          │                 │
          ▼                 ▼
    HTML/JSON файлы    manifest.json
    (в папке сайта)    (индекс контента)
          │
          ▼
       Deploy

Ключевое: vault и проект сайта — разные директории. Sync-скрипт читает из vault, пишет в проект. Vault не знает о сайте. Сайт не знает об Obsidian.

Ключевые принципы

1. Vault — единственный источник контента

Контент живёт только в vault. Никаких копий в docs/, content/, или в коде. Sync-скрипт всегда читает из vault напрямую. Чтобы обновить текст на сайте — редактируешь .md в Obsidian, запускаешь sync.

2. YAML frontmatter управляет поведением

Каждый .md файл содержит YAML frontmatter, который определяет, как этот файл обрабатывается sync-скриптом:

---
slug: getting-started       # URL-путь на сайте
type: page                  # тип вывода (page, fragment, data)
access: public              # доступ (public, authorized, cohort-code)
title: Начало работы        # заголовок (если отличается от # в теле)
description: Быстрый старт  # описание для манифеста и SEO
order: 1                    # порядок в навигации
---

YAML — это контракт между автором контента и sync-скриптом. Автор не трогает код — он управляет поведением через метаданные.

3. Папка определяет defaults, YAML — override

Каждая папка-источник имеет свои defaults (тип вывода, доступ). YAML frontmatter в конкретном файле может переопределить любой default. Это convention over configuration: положил файл в Blog/ — он станет публичной страницей без дополнительных настроек. Но можешь добавить access: authorized если нужно.

4. Три формата вывода

Standalone page (type: page) — полная HTML-страница. Работает без SPA, индексируется поисковиками. Для публичного контента, лендингов, блога.

Fragment (type: fragment) — JSON с { title, html }. SPA-компонент загружает и рендерит внутри layout. Для контента, встроенного в приложение (курсы, документация с навигацией).

Structured data (type: data) — markdown-таблицы парсятся в JSON-массивы. Для списков, каталогов, расписаний — любых данных, которые удобно вести как таблицу в Obsidian.

5. Sync отделён от build

Sync запускается локально — ему нужен доступ к vault. Build запускается где угодно (CI, Docker) — ему vault не нужен, он работает с уже готовыми файлами. Sync кладёт результат в папку проекта, build собирает из неё.

6. Автогенерируемый манифест

Sync-скрипт создаёт manifest.json со списком всего контента: slug, title, description, type, access, order. Компоненты сайта используют манифест для навигации, списков, "следующий/предыдущий". Новый файл в vault = новый пункт автоматически.

Workflow

Обновить контент

1. Редактируешь .md в Obsidian
2. Запускаешь sync (команда, skill, или автоматика)
3. Деплоишь

Добавить новый контент

1. Создаёшь .md файл в нужной папке vault
2. Добавляешь YAML frontmatter (минимум: slug)
3. Запускаешь sync → файл подхватывается автоматически

Добавить новый тип контента

1. Создаёшь папку в vault
2. Определяешь defaults для этой папки в конфиге sync-скрипта
3. При необходимости — новый UI-компонент на сайте

Компоненты решения

Sync-скрипт — ядро CMS

Входные данные:

• Путь к vault
• Маппинг: папка → defaults (тип, доступ, выходная директория)

Что делает:

• Сканирует папки-источники
• Для каждого .md: парсит YAML frontmatter, мержит с defaults
• Конвертирует markdown в целевой формат (HTML, JSON, structured data)
• Генерирует manifest.json
• Логирует: сколько файлов обработано, какие пропущены, ошибки

Markdown-процессор

Конвертирует .md → HTML с учётом Obsidian-специфики:

• -- → — (тире)
• Callout-блоки (> [!note])
• Wikilinks (оставить как есть, конвертировать в обычные ссылки, или обработать кастомно)
• Подсветка кода

Может быть любая библиотека: marked, remark, markdown-it, pandoc.

Генератор манифеста

Собирает метаданные всех обработанных файлов в один JSON:

[
  {
    "slug": "getting-started",
    "title": "Начало работы",
    "description": "Быстрый старт",
    "type": "page",
    "access": "public",
    "order": 1
  }
]

Компоненты сайта используют манифест для построения навигации, списков контента, "следующий/предыдущий".

Парсер таблиц (для type: data)

Markdown-таблицы → JSON-массивы объектов. Заголовки таблицы = ключи. Каждая строка = объект. Полезно для: списков видео, расписаний, каталогов, FAQ.

Вопросы для адаптации

Перед сборкой агент задаёт пользователю эти вопросы.

Контент

• Какие типы контента будут на сайте (блог, документация, гайды, курсы)?
• В каких папках vault лежит контент для сайта?
• Есть ли контент с ограниченным доступом? Как определяется доступ?
• На каком языке контент?

YAML

• Используешь ли ты уже YAML frontmatter? Какие поля?
• Есть ли обязательные поля в vault (LLM, date, type)?
• Как формировать slug — из имени файла или всегда явно в YAML?

Сайт

• На каком стеке сайт (React, Next.js, Astro, Hugo, plain HTML)?
• Нужен ли SPA с динамической загрузкой или достаточно статических страниц?
• Где хостится (VPS, Vercel, Netlify, GitHub Pages)?
• Как сейчас происходит деплой?

Workflow

• Кто редактирует контент — один человек или команда?
• Нужен ли автоматический sync при изменении файлов, или ручной запуск?
• Нужна ли preview перед деплоем?

Нюансы и грабли

Vault и проект — разные миры

Sync-скрипт должен работать на машине, где доступен vault. CI/CD обычно не имеет доступа к vault. Решение: sync локально, commit результатов, build в CI. Или: sync как pre-deploy шаг.

Имена файлов vs slug

Имена файлов в Obsidian могут содержать пробелы, кириллицу, спецсимволы. Slug в URL — нет. Всегда используй slug в YAML frontmatter. Не полагайся на имя файла как slug.

Wikilinks в выводе

Obsidian [[wikilinks]] не имеют смысла на сайте. Варианты: заменять на HTML-ссылки (если целевой файл тоже на сайте), убирать (оставлять только текст), или оставлять как есть (если контент внутри SPA и wikilinks не видны).

Markdown-процессор не понимает Obsidian

Стандартные markdown-библиотеки не знают про callout-блоки, embed-синтаксис (![[file]]), и другие Obsidian-расширения. Нужен этап препроцессинга, который конвертирует Obsidian-специфику до передачи в markdown-процессор.

Контент, переплетённый с UI

Маркетинговые страницы (программа курса, цены, CTA) часто смешивают текст с визуальными компонентами. Автоматический sync здесь не работает. Варианты: vault-файл как source of truth для копирайтинга (перенос в код вручную), или разделение на текстовую и UI-части.

Манифест может устареть

Если sync не запускался, а файлы менялись — манифест не актуален. Решение: запускать sync перед каждым деплоем, или добавить проверку "есть ли неsynced файлы".

Масштабирование

Паттерн работает для:

• Блог — Blog/ → standalone HTML-страницы
• Документация — Docs/ → fragments внутри SPA с навигацией
• Курсы — Course/ → fragments с контролем доступа
• Лендинги — Landing/ → standalone HTML
• Changelog — Changelog/ → structured data или страницы
• Видеотека — Videos/ → structured data (таблицы → JSON)
• FAQ — FAQ/ → structured data
• Email-рассылки — Emails/ → source of truth для копирайтинга (ручной sync)

Для каждого нового типа: папка в vault + defaults в конфиге sync + (опционально) UI-компонент.

Реализация-пример

Obsidian + любой веб-фреймворк + sync-скрипт на любом языке.

Компонент	Реализация
Vault	Obsidian vault с папками по типам контента
YAML frontmatter	slug, type, access, title, description, order
Sync-скрипт	Скрипт на любом языке: читает vault, парсит YAML, конвертирует markdown, генерирует manifest
Markdown-процессор	marked, remark, markdown-it, pandoc — любая библиотека с расширениями
Манифест	manifest.json — массив объектов с метаданными всех страниц
Сайт	Любой фреймворк (React, Astro, Next.js, Hugo) или plain HTML
Деплой	Ручной, CI/CD, или по команде агента

Типичный результат: из 10-30 .md файлов в vault получается полноценный сайт с навигацией, SEO, и обновлением контента без перезапуска фреймворка.

Выходные артефакты

После сборки у пользователя должны быть:

Артефакт	Описание	Как проверить
Папки контента в vault	Организованы по типам	Существуют, файлы с YAML frontmatter
Sync-скрипт	Читает vault, генерирует output	Запуск обрабатывает все файлы без ошибок
manifest.json	Индекс всего контента	Содержит записи для каждого .md файла
Output-файлы	HTML/JSON в папке проекта	Файлы существуют, контент корректный
Команда деплоя	Способ опубликовать на сайт	Деплой работает, контент на сайте
Skill или команда	Способ запуска sync одной командой	"Обнови сайт" → sync + deploy