Decap CMS Configuration: folder, files, widgets — full setup in 1 day
We often encounter situations where CMS becomes a black box after configuration: editors get confused with fields, content saves in the wrong place, slugs conflict. It all comes down to one YAML file — config.yml. Proper configuration of Decap CMS collections is not just a list of fields, but an architecture of content. If you think it through upfront, you save hours of edits and frustration. Over 6 years of working on projects with Decap CMS, we have developed approaches that help avoid typical mistakes. For example, setting up collections for an online store with product catalog, categories, and brands took 6 hours. After implementation, editors create products 2x faster, and the number of publication errors decreased by 40%.
Two types of collections: folder vs files
| Parameter | Folder collection | Files collection |
|---|---|---|
| Purpose | Multiple similar entries (articles, products) | Fixed pages (home, contacts) |
| Create new entries | Yes (create: true) | No, only editing |
| Slug | Generated from template | Not needed |
| Example | Blog, catalog, reviews | Home, about, 404 |
collections:
# Folder collection
- name: blog
label: Blog
folder: content/blog
create: true
delete: true
slug: "{{slug}}"
fields:
- { label: Title, name: title, widget: string }
- { label: Content, name: body, widget: markdown }
# Files collection
- name: pages
label: Pages
files:
- label: Home page
name: home
file: content/home.yaml
fields:
- { label: Hero title, name: hero_title, widget: string }
- { label: Hero subtitle, name: hero_subtitle, widget: text }
- label: About company
name: about
file: content/about.md
fields:
- { label: Title, name: title, widget: string }
- { label: Content, name: body, widget: markdown }
Configuring collections for different content types
For an informational site, two collections suffice: articles (folder) and pages (files). For an online store, you need product catalog, categories, brands. Rule: one content type — one collection. Do not try to fit products and articles into one folder, otherwise, you will clutter the interface. Folder collection is better for a blog than Files collection, as it allows creating new entries without modifying the config.
Widgets: full set for real projects
fields:
# Basic
- { label: String, name: title, widget: string, required: true }
- { label: Text, name: description, widget: text }
- { label: Number, name: order, widget: number, value_type: int, default: 0 }
- { label: Boolean, name: featured, widget: boolean, default: false }
- { label: Date, name: date, widget: datetime, format: "YYYY-MM-DD" }
# Select from list
- label: Category
name: category
widget: select
options:
- { label: News, value: news }
- { label: Cases, value: cases }
- { label: Analytics, value: analytics }
# Media file
- { label: Cover, name: cover, widget: image, required: false }
# Markdown editor
- label: Content
name: body
widget: markdown
modes: [rich_text, raw]
# List of strings
- { label: Tags, name: tags, widget: list, required: false }
# Nested object (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 }
# List of objects (features)
- label: Features
name: features
widget: list
fields:
- { label: Icon, name: icon, widget: string }
- { label: Title, name: title, widget: string }
- { label: Description, name: description, widget: text }
Decap CMS offers over 12 widget types; we've covered the most useful. For example, using relation instead of manual select reduces data duplication by 3x.
Importance of proper widget configuration
Incorrect widget selection leads to editing problems. For example, use markdown for long texts, not text — otherwise the editor cannot format. For numeric values, always specify value_type and default to avoid empty fields. We guarantee that after our setup, editors will not encounter such issues.
Sorting and filtering
For editors' convenience, add sortable_fields and view_filters. This allows sorting entries by date, title, or custom field, and filtering by status.
- name: team
label: Team
folder: content/team
create: true
sortable_fields: ['name', 'position', 'order']
view_filters:
- label: Active only
field: active
pattern: true
- label: Managers
field: department
pattern: management
view_groups:
- label: By department
field: department
Related collections via relation
The relation field accepts parameters: collection — source collection name, search_fields — fields for search, value_field — what is saved in the file. For example: widget: relation, collection: team, search_fields: ['name'], value_field: name. In the markdown file, the author's name is saved as a string. If you need an ID — change value_field: "{{slug}}".
Advanced settings: nested and conditional
- name: docs
label: Documentation
folder: content/docs
create: true
nested:
depth: 3
summary: "{{title}}"
meta: { path: { label: Path, widget: parent-path } }
fields:
- label: Block type
name: type
widget: select
options: [text, video, gallery]
- label: Text
name: text
widget: markdown
condition:
field: type
value: text
- label: Video URL
name: video_url
widget: string
condition:
field: type
value: video
i18n of collections
i18n:
structure: multiple_files
locales: [ru, en]
default_locale: ru
collections:
- name: services
label: Services
folder: content/services
create: true
i18n: true
fields:
- { label: Title, name: title, widget: string, i18n: true }
- { label: Slug, name: slug, widget: string, i18n: duplicate }
- { label: Content, name: body, widget: markdown, i18n: true }
Common mistakes and how to avoid them
| Mistake | Consequences | Solution |
|---|---|---|
| Not specifying folder for folder collection | Files created in GitHub root | Always specify folder |
| Too many required fields | Editors get tired and skip important ones | Keep only key fields required |
| Relation without search_fields | Dropdown becomes infinite | Add at least search_fields: ['name'] |
| Missing default_locale with i18n | Build fails, CMS cannot detect language | Specify default_locale |
What is included in Decap CMS collections setup
- Content schema development for your project (5–8 content types).
- Configuration of widgets, relation, nested, i18n.
- Testing on real data (up to 50 entries).
- Documentation for editors (description of each field).
- Support for 2 weeks after delivery — we fix shortcomings.
Deliverables
- Detailed documentation (Notion or Markdown) explaining each collection and field.
- Admin access to Decap CMS with test data (up to 50 entries).
- 1-hour training session for editors via Zoom.
- 2 weeks of post-delivery support via Slack or email.
- Configuration files committed to your repository with clean git history.
How to debug Decap CMS configuration?
Most common reasons for non-working CMS after editing config.yml:
- YAML syntax — one extra or missing space breaks the file structure, CMS does not load. Check with an online validator before committing.
- Incorrect backend path — ensure
name: git-gatewaymatches your provider, andbranchpoints to the correct repository branch. - Empty required fields — if an editor cannot save an entry, check that all fields with
required: truehavedefault. - Relation does not find collection — the
collectionfield in the relation widget must match thenameof the target collection, notlabel. - i18n files are not created — with
structure: multiple_files, a separate directory for each language is needed.
How we implement Decap CMS collection configuration?
- Conduct interviews with editors — find out which fields are used most often and what causes difficulties.
- Design the collection schema: define types, widgets, and relations between collections.
- Write
config.yml, test on staging — create, edit, delete entries. - Document each field, explain the purpose of widgets to the editorial team.
- Hand over with 2 weeks support — promptly fix comments.
Official Decap CMS documentation
Timeframes and cost
Basic setup (up to 5 collections, without i18n): 4–8 hours ($500–$1000). Medium project (6–10 collections, relation): 1 day ($1000–$2000). Complex project (with i18n, conditional fields, 10–15 collections): 1–2 days ($2000–$4000). Cost is determined after analysis. Contact us to discuss your Decap CMS configuration. Get a consultation from an engineer with 6 years of experience with this CMS. We guarantee quality and adherence to deadlines.