---
title: "Формат документа"
id: "1976"
type: "page"
slug: "documents"
published_at: "2026-09-20T15:42:59+00:00"
modified_at: "2026-10-28T18:13:30+00:00"
url: "https://pastukhov.com/agents/portal/docs/documents/"
markdown_url: "https://pastukhov.com/agents/portal/docs/documents.md"
excerpt: "Страница в портале — это не запись в базе, а папка с файлами. Внутри лежит…"
---

# Формат документа

[https://pastukhov.com/agents/portal/docs/documents/.md](https://pastukhov.com/agents/portal/docs/documents/.md)

Страница в портале — это не запись в базе, а папка с файлами. Внутри лежит описание страницы и её тексты. Такой формат выбран специально: файлы можно хранить в истории версий, легко читать и переносить, и они не зависят от конкретного сервера.

## Страница — это папка

У каждой страницы своя папка. Внутри — три основных вида содержимого:

- **Файл описания** — здесь записано всё о странице: заголовок, описание, иконка, из каких блоков она состоит, какой у неё доступ и настройки.
- **Текстовые файлы** — крупные тексты блоков вынесены из описания в отдельные файлы. Так описание остаётся коротким и обозримым, а правки в истории версий — понятными. В таком тексте могут быть и схемы-диаграммы.
- **Папка файлов** — картинки и другие файлы страницы лежат рядом, в отдельной папке. Из неё же берутся картинки и документы, которые показываются прямо в тексте.

Выглядит это примерно так:

```
portal/                          корень портала
├── document.json                 описание главной страницы
├── {блок}.md                     тексты блоков главной
├── comments.json                 комментарии к главной (если есть)
├── assets/                       картинки главной
└── news/
    ├── document.json
    ├── {блок}_intro.md
    └── comments.json
```

## Зачем именно так

Хранение контентом обычными файлами даёт три выгоды. Первая — чистая история версий: каждое сохранение переписывает описание целиком, поэтому в истории видно именно то, что изменилось, а не сотни строк случайных перестановок. Вторая — переносимость: папку портала можно скопировать на другой сервер и открыть там без экспорта и импорта. Третья — независимость: если завтра вы решите перейти на другой сервер или другой бренд, контент останется с вами.

## Что лежит в описании страницы

- **Заголовок** — название страницы, оно же показывается в дереве. Обязательное поле.
- **Описание и иконка** — короткая пояснительная строка под заголовком и значок страницы в дереве.
- **Блоки** — из чего собрана страница, по порядку. Может быть пустым списком, если страница пока только задумана.
- **Переменные** — объявленные переменные для страниц-образцов (см. [Шаблоны и переменные](/agents/portal/docs/templates) ).
- **Доступ** — кто может открыть страницу: только администраторы, сотрудники после входа или все желающие (см. [Доступ к страницам](/agents/portal/docs/access) ).
- **Настройки** — ширина страницы, участие в меню, рекомендация от агента и настройки самого сайта: его название, значок и глубина меню.

## Что сервер ведёт сам

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

## Комментарии к странице

Кроме описания, текстов и картинок, у страницы может быть ещё один файл — с комментариями. Это замечания администратора к выделенному тексту страницы: очередь просьб, которую агент разбирает прямо у страницы, а отвечает в чате. Такой файл появляется, только когда комментарии есть, а вместе с последним замечанием исчезает. Подробнее — в разделе [Комментарии к страницам](/agents/portal/docs/comments)
.

## Картинки и файлы в тексте

Файл из папки страницы можно поставить прямо в текст — не отдельным блоком, а внутри абзаца или списка:

- **Картинка** — схема, таблица, фото — показывается в тексте на своём месте, без лишних нажатий.
- **Другой файл** — договор, выгрузка, презентация — скачивается по ссылке, не уводя читателя со страницы.

Всё остальное в тексте остаётся как написано: ссылки на другие сайты, якоря внутри страницы, ссылки на другие страницы портала и примеры в блоках с кодом портал не трогает. Работает это и на публичном сайте: посетитель видит ту же картинку и скачивает тот же файл.

## Адреса страниц

Адрес страницы — это путь по папкам от корня портала. Имена пишутся латиницей в нижнем регистре через дефис, например `press-releases`. Отдельный случай — папка с именем в квадратных скобках, например `[tag]`: это образец, который обслуживает сразу много адресов. Подробнее — в разделе [Шаблоны и переменные](/agents/portal/docs/templates)
.

## Подстановка значений

Когда страница читается, сервер подставляет значения переменных во все её строки: в заголовок страницы, описание, заголовки блоков, подписи кнопок и адреса ссылок. Тексты блоков подставляются уже в браузере — так образец мгновенно показывает нужный вариант при переходе по адресу.

## Чего в контенте нет

Контент портала лежит в отдельной папке репозитория, а служебные данные — в стороне от него, в томе `/apps/portal`. Окружение Python (набор программ, которыми считаются скрипты), рабочая папка для файлов скриптов и пометки о непрочитанных страницах — всё это служебные данные сервера. Они не входят в историю версий и при копировании папки контента на другой сервер создаются заново.

Дальше: как из блоков собирается страница — в разделе [Блоки](/agents/portal/docs/blocks)
; откуда берутся живые цифры — в разделе [Источники данных и визуализации](/agents/portal/docs/sources)
; как вести много адресов одной страницей — в разделе [Шаблоны и переменные](/agents/portal/docs/templates)
; чем управляет агент — в разделе [Управление агентом](/agents/portal/docs/management)
.

[← Оглавление документации](/agents/portal/docs)