---
title: "Формат документа"
id: "1976"
type: "page"
slug: "documents"
published_at: "2026-09-20T15:42:59+00:00"
modified_at: "2026-09-21T00:00:47+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                     тексты блоков главной
├── assets/                       картинки главной
└── news/
    ├── document.json
    └── {блок}_intro.md
```

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

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

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

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

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

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

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

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

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

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

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

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

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

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