Blocks

Disable or enable

All blocks are available by default but if you want hide or add your blocks, you can do it:

params:
  admin:
    blocks:
      # Array of available blocks
      enable:
        - alert
        - cta
        - editorial
        # …

Personalize fields

params:
  admin:
    blocks:
      # Array of available fields for a block
      # e.g with paragraph block
      paragraph:
        fields:
          - title
          - text_markdown
          # …

Notes

The paragraph, paragraph-list and editorial blocks can carry notes, linked to the text by [*] markers. The field is hidden by default:

params:
  admin:
    blocks:
      paragraph:
        notes: true
      paragraph-list:
        notes: true
      editorial:
        notes: true

notes is ignored when the block’s fields are overridden: add notes to the list instead.

Block icon

An icon is declared per icon set. See Setup.

params:
  admin:
    blocks:
      alert:
        icon:
          material_icons: warning_amber

Appearance

Appearance is carried by a single ui object instead of sitting flat at the root of the block. A block opts in by listing ui among its fields, like any other field.

blocks:
  - type: informations
    ui:
      column: 3
      ratio: 1
      grid: large
      offset: center
      align: center
      theme: dark
      scrollsnap: md

Choosing which controls appear

v1 hardcoded the object to theme, grid and offset. In v2 the set is driven by params, so you decide which controls the editor sees and which values they offer.

params:
  admin:
    fields:
      grid:
        options: [container, small, medium, large, full]
      theme:
        options: [light, dark, accent]
      ui:
        fields: [theme, grid, offset, align]

The field is labelled Layout & appearance instead of UI.

These params decide which controls the editor sees, never what they hold. No ui field is prefilled, because a CMS default is saved to the front matter of every entry created after it: the content would carry the site’s design decisions, and changing one later would leave the existing entries behind.

A look given to a whole block type belongs outside the content, in the blocks file of the config collection.

Fields that depend on another

In Decap CMS and Sveltia CMS, a select hides the sibling fields that do not apply to its value. Hiding is visual only: a hidden field keeps its value, the front matter keeps its shape, and the other CMS show every field.

• layout: the carousel settings only show with the carousel layout, the scroll snap with the grid. A block left without layout takes its look from the blocks file of the config collection and shows neither: choosing a layout reveals the fields that override that file. The blocks file itself shows every field, and the blocks without a layout field (comparison, datas, informations) always show their scroll snap.
• source, in the selection blocks: the manual selection shows the items, a taxonomy filter its terms, the children of a page the parent page.

params:
  admin:
    fields:
      layout:
        toggle:          # merged key by key with the default
          grid: [scrollsnap, column]
      selected_source:
        toggle: false    # every field shown, whatever the source

toggle maps a value to the sibling fields it shows. A field listed under no value is never hidden, and the empty key stands for a field left empty. The layout map ships with the admin and keeps, for each block, the layouts it offers. The selected_source map is computed from the sources of each collection, and a map given here is laid over it. false shows every field. Both settings apply to every block at once.

How to create a block

Fields allowed

Add a HTML block file contains fields (e.g. alert.html).

layouts/
└── partials/
    └── admin/
        └── blocks/
            └── fields/

Content of fields:

{{- $fields := slice 
  "text_markdown" 
  "state" 
  "ui" -}}
  
{{- $fields = partial "admin/func/GetFields.html" (dict "block" . "fields" $fields) -}}

{{- return $fields -}}

Block types

Add a YAML block file with config (e.g. alert.yml).

layouts/
└── partials/
    └── admin/
        └── blocks/
            └── types/

Content of block type:

{{- $fields := partial "admin/blocks/fields/alert.html" . -}}

{{- $args := dict 
  "label" (i18n "admin.blocks.alert.label")
  "name" "alert"
  "collapsed" false
  "fields" $fields
  -}}

{{ partial "admin/widgets/object.js" $args }}

And add it in enable blocks: see above

Examples

List of Hugolify blocks