The most efficient way to convert a diazo theme (or plain html/css/js) to Volto

I'm looking for recommendations on moving an existing diazo theme to Volto.
By design, theming Volto using Semantic UI components, theme shadowing and custom less files seems relatively straightforward. If I follow this approach I'll likely be reimplementing the look with semantic UI components. This doesn't feel very efficient.

Given that my theme is based on a standard html structure, understanding the best way to "reactize" such a structure is likely a good start. The theme provides an index.html file and assets arranged in three folders - css, images and js.

The following resources look like the best starting point for getting this done:

Any pointers would be appreciated.

So far what I'm finding looks pretty tedious.

In the volto-educal-theme, each part of the theme is made into a component and then the images associated with that component are imported separately.
For example... the Footer.jsx
relies on a Logo image:

import LogoImage from '@plone-collective/volto-educal-

It is later called like this:

 <Image src={LogoImage} />

But what if the image is in css?

It's a pretty expensive process. You end up having to shadow a lot of components and hope that the structure you are replacing in volto maps reasonably easily to the structure you want to put in it's place. At the moment each volto version requires work in reintegrating the volto changs into the shadowed components. I'm not sure the idea you can have both pastanaga and your custom theme split for different views works. Since the reason you are paying all this theming cost is to get a WYSIWYG editing experience so unless you combine the themes you lose out of on that.

Or at least thats one perspective on working on GitHub - pretagov/nsw-design-system-plone6-kit.

On the plus side it is true that any React developer can do this work and it's easier to customise the editor experience.

This is a crude summary of what I'm picking up...
The "Volto way" seems to be leading me towards an approach where I customise at the level of the components (either by shadowing or implementing my own) and then assemble the final experience together with volto views or manually with the block editor.


So... is anyone using tools like BuilderX or ReactStudio to solve this problem?

Hi David,

The premise that you are bringing up not only relates to old Plone themes and a Volto SemanticUI theme... You want a theme implemented in X to be implemented in Y.

Being X and Y so different, so they share nothing... using a different HTML structure and classes, pre-processor of choice, the JS on top, etc...

That is though. But if you are pragmatic and instead of trying to "translate" from one to another, you just adapt the theme to Y be like X, is not that more easy?

David, remember that you are not constrained to anything in Volto. You don't have to use the SemanticUI components if you don't want to. They are there to help you, as a Swiss knife, not to constrain you, so you can use others or your own.

This also applies to the SemanticUI theme... just don't use it. Use extras escape hatch CSS. Take a look at theme or at ploneconf2023 repo one. These are "modern" real life themes. Also look at EEA themes. Finally look at the theme I'm working on in my company: GitHub - kitconcept/volto-light-theme This one is very disruptive, but should be the embryo of the future Volto theming story.

The vision is that Plone on the frontend is not even constrained by Volto, and we are heading to a multi-frontend approach, where we will provide the meaning to query the content from the backend from any frontend using unified libraries. Same for the component libraries, so you can use them in NextJS, Remix, Vue, Angular, SvelteKit, etc...


Thanks @sneridagh,
I need to spend some time with these examples. I'm onboard conceptually. I know enough to get a theme done with Volto (with help from a React developer). I don't know yet how to theme Volto in a manner that is more cost effective and efficient than Diazo. This may change in the future as I explore more.

The low resolution version of the story I want (or think I want) is:

  1. Build out the experience using a visual tool (my go to tool is currently Webflow but I may need to replace this with BuilderX, Anima or something that gets me JSX/React components as an output)
  2. Move the output over to my Volto project

@pigeonflight volto just doesn't work that way. It's not diazo.
But modern web layouts seem to be more and more alike so I suspect the volto way is not that far away from other frameworks.
For example we found when converting the NSW design system most things fit.

Perhaps the only example that didn't fit well is sections which volto doesn't have a concept of. The DS makes everything go into at least one section but it would be annoying to make the editor create containers everytime they wanted to create a normal page. So in the end we did a little magic similar to daizo where we manipulated html of the whole page based on the settings of multiple blocks. We made which section a block is in a property of all blocks.
This does work but it breaks WYSIWYG since the editor HTML is no longer what you get on save.

It would be better if volto had the section concept built into the editor so all blocks are in a section by default but you can start a new one at any point easily.
So the answer is really to improve volto so it has enough basic building blocks that are close in structure to what your end result.

And as I mentioned above, if you want custom HTML and you do have the right basic structure then you still have to essentially rewrite each of the blocks you will use get them to write the HTML you want and once you do that shadowing you are now responsible for incorporating any changes from the base version into your copy. There isn't a separation of theme and function unless you keep the html as semantic UI. At least not yet.
e.g if your listing block needs different html then you now have your own copy of the listing block to maintain.

Reformulating my question...
"How can I theme Volto in a manner that is comparable in efficiency to Diazo?"

I don't need it to be diazo. I think volto is very sane, I'm just looking for ways to avoid paying the component "tax". By tightly coupling theme to function it seems to leave us with no choice but customise on a component by component basis. There are advantages to components walking around with their styles, I know this. Once I've exhausted the options I will lament a bit more then accept it as my lot.

Or... I'm missing something and once the lightbulb goes off I'll discover that volto theming is far more efficient than diazo theming.

@pigeonflight IMO you can't
Volto takes a jbot style approach where there is no separation of CMS, view logic and theme... unless you want to theme only with semantic UI CSS. of course I might also be missing something here.

But I think the main reason you wan to use volto is because you want an editing experience where what you edit is what gets rendered on the final page (pretty much).
Maybe you can build something with JS on top of react that fiddles with the JS after the react has rendered components to do do global theme changes to components without having to shadow (override) the react components that make up volto. I'm not sure if it's possible but if it is, its going to cost in performance and like diazo would break if the html it uses changes. On the other hand it be a separation of concerns.
But we have taken the recommend route of shadowing/overriding. Which means we pay the tax of every updating having to do diffs and remerging our code with any underlying changes.
On the other hand you can change not just the rendering but the editing UI for that block and it's business logic. And the coding experience you need to do this work is react, not really any uncommon plone knowledge.
And as I mentioned, the editing experience is tightly linked to components and blocks. if there was a way to fiddle with the html between blocks it might make for a strange editing experience.

Quick update:
I'm looking into Webflow's Devlink, it lets you build React components directly in the Webflow Designer.

Perhaps my Webflow expertise can still be useful on modern, volto-based, non-diazo Plone projects. Probably won't be doing component shadowing thought :thinking: