Конфигурация коллекций Decap CMS: folder, files, виджеты — полная настройка за 1 день.
Мы часто сталкиваемся с ситуацией, когда CMS после настройки превращается в «чёрный ящик»: редакторы путаются в полях, контент сохраняется не там, slug-и конфликтуют. Всё упирается в один YAML-файл — config.yml. Правильная конфигурация коллекций Decap CMS — это не просто список полей, а архитектура контента. Если её продумать заранее, вы сэкономите часы правок и нервов. За 6 лет работы над проектами с Decap CMS мы выработали подходы, которые помогут избежать типичных ошибок. Например, настройка коллекций для интернет-магазина с каталогом товаров, категорий и брендов заняла 6 часов. После внедрения редакторы создают товары в 2 раза быстрее, а количество ошибок при публикации сократилось на 40%.
Два типа коллекций: folder vs files
| Параметр | Folder collection | Files collection |
|---|---|---|
| Назначение | Множество однотипных записей (статьи, товары) | Фиксированные страницы (главная, контакты) |
| Создание новых записей | Да (create: true) | Нет, только редактирование |
| Slug | Генерируется из шаблона | Не нужен |
| Пример | Блог, каталог, отзывы | Главная, о нас, 404 |
collections:
# Folder collection
- name: blog
label: Блог
folder: content/blog
create: true
delete: true
slug: "{{slug}}"
fields:
- { label: Заголовок, name: title, widget: string }
- { label: Контент, name: body, widget: markdown }
# Files collection
- name: pages
label: Страницы
files:
- label: Главная страница
name: home
file: content/home.yaml
fields:
- { label: Заголовок hero, name: hero_title, widget: string }
- { label: Подзаголовок, name: hero_subtitle, widget: text }
- label: О компании
name: about
file: content/about.md
fields:
- { label: Заголовок, name: title, widget: string }
- { label: Контент, name: body, widget: markdown }
Настройка коллекций для разных типов контента
Для информационного сайта достаточно двух коллекций: статьи (folder) и страницы (files). Для интернет-магазина понадобится каталог товаров, категории, бренды. Правило: один тип контента — одна коллекция. Не пытайтесь уместить товары и статьи в одну folder, иначе загромоздите интерфейс. Folder collection лучше Files collection для блога, так как позволяет создавать новые записи без правки конфига.
Виджеты: полный набор для реальных проектов
fields:
# Базовые
- { label: Строка, name: title, widget: string, required: true }
- { label: Текст, name: description, widget: text }
- { label: Число, name: order, widget: number, value_type: int, default: 0 }
- { label: Булево, name: featured, widget: boolean, default: false }
- { label: Дата, name: date, widget: datetime, format: "YYYY-MM-DD" }
# Выбор из списка
- label: Категория
name: category
widget: select
options:
- { label: Новости, value: news }
- { label: Кейсы, value: cases }
- { label: Аналитика, value: analytics }
# Медиафайл
- { label: Обложка, name: cover, widget: image, required: false }
# Markdown-редактор
- label: Контент
name: body
widget: markdown
modes: [rich_text, raw]
# Список строк
- { label: Теги, name: tags, widget: list, required: false }
# Вложенный объект (SEO)
- label: SEO
name: seo
widget: object
collapsed: true
fields:
- { label: Meta title, name: title, widget: string, required: false }
- { label: Meta description, name: description, widget: text, required: false }
- { label: OG Image, name: og_image, widget: image, required: false }
# Список объектов (преимущества)
- label: Преимущества
name: features
widget: list
fields:
- { label: Иконка, name: icon, widget: string }
- { label: Заголовок, name: title, widget: string }
- { label: Описание, name: description, widget: text }
Важность правильной конфигурации виджетов
Неправильный выбор виджета ведёт к проблемам с редактированием. Например, для длинных текстов используйте markdown, а не text — иначе редактор не сможет форматировать. Для числовых значений обязательно указывайте value_type и default, чтобы не было пустых полей. Мы гарантируем, что после нашей настройки редакторы не столкнутся с такими проблемами.
Сортировка и фильтрация
Для удобства редакторов добавьте sortable_fields и view_filters. Это позволит сортировать записи по дате, заголовку или кастомному полю, а также фильтровать по статусу.
- name: team
label: Команда
folder: content/team
create: true
sortable_fields: ['name', 'position', 'order']
view_filters:
- label: Только активные
field: active
pattern: true
- label: Менеджеры
field: department
pattern: management
view_groups:
- label: По отделу
field: department
Связанные коллекции через relation
Поле relation принимает параметры: collection — имя коллекции-источника, search_fields — поля для поиска, value_field — что сохранится в файле. Например: widget: relation, collection: team, search_fields: ['name'], value_field: name. В Markdown-файле сохранится имя автора как строка. Если нужен ID — меняем value_field: "{{slug}}".
Продвинутые настройки: nested и conditional
- name: docs
label: Документация
folder: content/docs
create: true
nested:
depth: 3
summary: "{{title}}"
meta: { path: { label: Путь, widget: parent-path } }
fields:
- label: Тип блока
name: type
widget: select
options: [text, video, gallery]
- label: Текст
name: text
widget: markdown
condition:
field: type
value: text
- label: URL видео
name: video_url
widget: string
condition:
field: type
value: video
i18n коллекций
i18n:
structure: multiple_files
locales: [ru, en]
default_locale: ru
collections:
- name: services
label: Услуги
folder: content/services
create: true
i18n: true
fields:
- { label: Заголовок, name: title, widget: string, i18n: true }
- { label: Слаг, name: slug, widget: string, i18n: duplicate }
- { label: Контент, name: body, widget: markdown, i18n: true }
Распространённые ошибки и как их избежать
| Ошибка | Последствия | Решение |
|---|---|---|
| Не указана папка для folder collection | Файлы создаются в корне GitHub | Всегда указывайте folder |
| Слишком много обязательных полей | Редакторы устают и пропускают важные | Оставьте обязательными только ключевые поля |
| Relation без search_fields | Выпадающий список становится бесконечным | Добавьте хотя бы search_fields: ['name'] |
| Отсутствие default_locale при i18n | Сборка падает, CMS не определяет язык | Укажите default_locale |
Что входит в настройку коллекций Decap CMS
- Разработка схемы контента под ваш проект (5–8 типов контента).
- Настройка виджетов, relation, nested, i18n.
- Проверка на реальных данных (до 50 записей).
- Документация для редакторов (описание каждого поля).
- Поддержка 2 недели после сдачи — правим недочёты.
Как отлаживать конфигурацию Decap CMS?
Наиболее частые причины неработающей CMS после правки config.yml:
- YAML-синтаксис — один лишний или пропущенный пробел нарушает структуру файла, CMS не загружается. Проверяйте через онлайн-валидатор перед коммитом.
- Неверный путь backend — убедитесь, что
name: git-gatewayсовпадает с вашим провайдером, аbranchуказывает на нужную ветку репозитория. - Пустые обязательные поля — если редактор не может сохранить запись, проверьте, что все поля с
required: trueимеютdefault. - Relation не находит коллекцию — поле
collectionв relation-виджете должно совпадать сnameцелевой коллекции, не сlabel. - i18n-файлы не создаются — при
structure: multiple_filesнужна отдельная директория для каждого языка.
Как мы внедряем конфигурацию коллекций Decap CMS?
- Проводим интервью с редакторами — выясняем, какие поля используются чаще всего и что вызывает затруднения.
- Проектируем схему коллекций: определяем типы, виджеты и связи между коллекциями.
- Пишем
config.yml, тестируем на staging-окружении — создание, редактирование, удаление записей. - Документируем каждое поле, объясняем назначение виджетов команде редакторов.
- Передаём в работу с поддержкой 2 недели — оперативно правим под замечания.
Официальная документация Decap CMS
Сроки и стоимость
Базовая настройка (до 5 коллекций, без i18n): 4–8 часов. Средний проект (6–10 коллекций, relation): 1 день. Сложный проект (с i18n, условными полями, 10–15 коллекций): 1–2 дня. Стоимость базовой настройки — от 5 000 ₽, сложный проект с i18n и relation — от 20 000 ₽. Свяжитесь с нами, чтобы обсудить вашу конфигурацию Decap CMS. Получите консультацию инженера с 6-летним опытом работы с этой CMS. Гарантируем качество и соблюдение сроков.