Инструкция для AI-агента: сайт документации на trip2g

Этот документ — инструкция для AI-агента. Читая его, агент знает, что именно создать, чтобы хранилище Obsidian превратилось в работающий сайт документации на trip2g.

Агент работает внутри распакованного хранилища. Задача — создать нужные файлы и объяснить пользователю, что сделать в веб-интерфейсе.

1. Корневой файл _index.md

Хранилище должно содержать файл _index.md в корне. Это главная страница сайта — trip2g открывает её при переходе на /.

Создай файл _index.md в корне хранилища:

---
title: Документация
description: Документация проекта.
content:
  - self
  - magazine
magazine_include_files: "**/*.md"
---

Добро пожаловать. Выберите раздел в навигации или используйте поиск.

Важно: файл называется именно _index.md. Без подчёркивания — это другой файл, он не будет главной страницей.

2. Структура хранилища

Создай минимальную структуру файлов:

_index.md          — главная страница
_header.md         — шапка сайта (логотип + навигация)
_footer.md         — подвал (опционально)
_left_sidebar.md   — левая боковая панель с навигацией
logo.png           — логотип (если есть)

docs/
  getting-started.md
  installation.md
  configuration.md

Файлы с префиксом _ скрыты из листинга сайта, но выполняют свою функцию. Обычные файлы (без _) видны посетителям.

3. Все заметки скрыты по умолчанию

По умолчанию все заметки видны только администратору. Чтобы сделать их публичными, пользователю нужно создать frontmatter-патч в веб-интерфейсе.

Скажи пользователю сделать следующее:

  1. Открыть админ-панель сайта
  2. Перейти в раздел Заметки и контент → Патчи
  3. Нажать + Add
  4. Заполнить форму:
    • Include: **/*.md
    • Description: all free
    • Expression (Jsonnet): { free: true }
  5. Нажать Submit

После этого все заметки станут публичными. Если нужно скрыть конкретные заметки — добавь в их frontmatter free: false.

Подробнее о патчах: Frontmatter-патчи.

4. Шапка сайта с логотипом

Создай файл _header.md в корне хранилища. trip2g автоматически использует его как шапку на всех страницах — никаких дополнительных настроек не нужно.

Шапка берёт из файла:

  • Первое изображение — становится логотипом сайта
  • Первый список — становится навигационными ссылками

Пример _header.md с логотипом:

![[logo.png]]

- [Главная](/)
- [Документация](/docs/getting-started)
- [О проекте](/about)

Если логотипа нет, опусти строку с изображением:

- [Главная](/)
- [Документация](/docs/getting-started)
- [О проекте](/about)

Файл логотипа (logo.png) должен лежать в хранилище рядом с _header.md или в папке assets/. Obsidian-ссылка ![[logo.png]] найдёт его автоматически.

5. Функциональные заметки навигации

Trip2g автоматически подхватывает четыре специальных файла из корня хранилища:

Файл Роль
_header.md Шапка: логотип + навигация
_footer.md Подвал
_left_sidebar.md Левая боковая панель
_right_sidebar.md Правая боковая панель

Создавать их все не обязательно — создай только те, что нужны.

Пример _left_sidebar.md для сайта документации:

### Начало работы

- [Введение](/docs/getting-started)
- [Установка](/docs/installation)
- [Настройка](/docs/configuration)

### Справочник

- [API](/docs/api)
- [FAQ](/docs/faq)

Используй ### для заголовков групп — не жирный текст. Интерфейс отображает ### как секционные метки.

Пример _footer.md:

- [Главная](/)
- [Документация](/docs/getting-started)

### Проект

- [GitHub](https://github.com/yourproject)
- [Changelog](/changelog)

Подробнее о функциональных заметках и glob-секциях для разных разделов сайта: Дефолтный шаблон.

6. Типовые заметки раздела

Каждая заметка документации — обычный markdown-файл. Frontmatter минимален:

---
title: Установка
description: Как установить и запустить проект.
---

## Требования

- Node.js 18+
- ...

## Шаги

Поле title обязательно — оно используется как заголовок страницы и в карточках magazine. Поле description используется в SEO и в превью карточек.

7. Внутренние ссылки (wikilinks)

Это хранилище Obsidian. Все внутренние ссылки должны использовать синтаксис [[wikilink]], а не markdown-ссылки вида [текст](путь).

Правила:

  • [[Название заметки]] — ссылка по имени заметки, без расширения и пути
  • [[Название заметки|Текст ссылки]] — с произвольным текстом
  • ![[logo.png]] — вставка изображения
  • Если две заметки имеют одинаковое имя в разных папках, Obsidian выбирает по кратчайшему уникальному пути от корня. Чтобы избежать неоднозначности, уточняй путь: [[docs/installation]] вместо [[installation]]
  • Вложенность не важна — [[installation]] найдёт заметку docs/installation.md из любого места хранилища

Markdown-ссылки [текст](путь) тоже поддерживаются, но только для внешних URL и якорных ссылок на заголовки (#section). Для навигации между заметками хранилища используй исключительно [[wikilinks]].

8. Мультиязычные сайты

Trip2g поддерживает сайты документации на нескольких языках: параллельные разделы для каждого языка, переключатель языков и автоматические hreflang-теги для SEO. Подробнее: Мультиязычные сайты.

Итоговый чеклист

Убедись, что в хранилище есть:

  • _index.md в корне с content: [self, magazine]
  • _header.md с логотипом и навигацией
  • _left_sidebar.md с разделами документации
  • Заметки контента в docs/
  • Патч { free: true } настроен в веб-интерфейсе

После синхронизации хранилища сайт готов.