Decap CMS Configuration: folder, files, widgets

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.