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

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

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 we implement Decap CMS collection configuration?

1. Conduct interviews with editors — find out which fields are used most often and what causes difficulties.
2. Design the collection schema: define types, widgets, and relations between collections.
3. Write config.yml, test on staging — create, edit, delete entries.
4. Document each field, explain the purpose of widgets to the editorial team.
5. 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.