Prerelease
v2 is published as prerelease tags only — the latest is v2.0.0-11. Go resolves stable versions by default, so hugo mod get will keep you on v1 unless you pin a prerelease explicitly.
v2 requires hugolify-theme v2. The two are versioned together and a mismatched pair fails silently — see Compatibility.
Install
# /config/_default/module.yaml
imports:
- path: github.com/hugolify/hugolify-theme/v2
- path: github.com/hugolify/hugolify-theme-bootstrap
- path: github.com/hugolify/hugolify-admin/v2
hugo mod get github.com/hugolify/hugolify-admin/v2@v2.0.0-11
Replace the tag with the most recent one — prereleases are published often and Go will not pick them up on its own.
See the latest prereleasesCompatibility
Pair the majors: a v1 project runs hugolify-admin v1 with hugolify-theme v1, a v2 project runs both in v2. One off-pair combination degrades gracefully, the other does not work at all.
| hugolify-theme v1 | hugolify-theme v2 | |
|---|---|---|
| hugolify-admin v1 | Supported | Partially supported |
| hugolify-admin v2 | Not supported | Supported |
admin v1 on theme v2 — partial
The theme resolves a block’s appearance through func/GetBlockUI, which reads the parameters from the root of the block and accepts a nested ui object as an override, with a fallback mapping the legacy background flag to the bg theme. Front matter written by admin v1 is therefore understood, and pages render as intended.
What you lose is reach, not correctness: admin v1 has no field for ratio or scrollsnap, so those two theme v2 controls cannot be set from the CMS. Every other control — column, align, grid, layout, offset, theme — comes through.
Useful as a transition, when you want to move the theme first and the admin later.
admin v2 on theme v1 — no
hugolify-theme v1 has no equivalent resolver and never reads ui, while admin v2 writes the appearance parameters there only.
This one fails silently
Nothing errors. The values are written where the theme is not reading, so blocks render with their default appearance and every control set from the CMS is quietly ignored.
Breaking changes
| v1 | v2 | |
|---|---|---|
| Module path | hugolify-admin | hugolify-admin/v2 |
| hugolify-theme | v1 or v2 | v2 |
| Weight widget | select (10, 20, 30…) | number input (min: 1, integer) |
| Background colour field | background-color.yml | background_color.yml |
| UI fields | hardcoded in the module | configurable through params |
If you relied on the stepped weight select, the previous behaviour is preserved in a separate field:
admin/fields/weight_select.yml
The UI object
A block or a hero has always carried a handful of appearance parameters — how many columns, which grid, how it is aligned. In v1 they sat flat at the root of the block, next to its content, and there were only a few of them.
They are now grouped into a single ui object, which separates what the block says from how it looks, and leaves room to grow without cluttering the block.
/content/_index.md
# Before — flat, and only a few parameters
blocks:
- type: informations
column: 3
ratio: 1
# After — everything under ui
blocks:
- type: informations
ui:
column: 3
ratio: 1
grid: large
offset: center
align: center
theme: dark
scrollsnap: md
This is a front matter change
hugolify-theme v2 reads these keys from ui, hugolify-theme v1 reads them from the root of the block. Moving to admin v2 therefore means moving to the theme v2 as well, otherwise the values are written where the theme is not looking.
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.
/config/_default/params.yaml
params:
admin:
fields:
grid:
options: [container, small, medium, large, full]
theme:
options: [light, dark, accent]
ui:
fields: [theme, grid, offset, align]
The field is now labelled Layout & appearance instead of UI.
Navigation
Header and footer menus each gain three levels, replacing the single menu of v1.
- Header — primary, secondary, tertiary
- Footer — primary, secondary, tertiary
The footer also accepts blocks, not just an information text.
New fields
| Field | Purpose |
|---|---|
ratio | Media aspect ratio, 1 being square |
scrollsnap | Breakpoints at which items scroll sideways (none, sm, md, lg, xl, all) |
selected_source | Choose block items manually or by taxonomy |
vertical_align | Vertical text alignment (start, center, end) |
image.src_mobile | Dedicated mobile image, used by the hero |
weight_select | The v1 stepped weight select, kept as an opt-in |
Other additions: a reorder configuration for collections (Sveltia CMS), blocks on the persons and products collections, firstname and lastname on persons, a file input for form fields, and an optional format on the datetime widget for Decap and Sveltia storage.