theming: provide more information about theming and styling by max-moser · Pull Request #988 · inveniosoftware/docs-invenio-rdm

max-moser · 2026-07-31T11:03:15Z

Previously, the section already contained a few snippets of information, but not really enough to convey a good overview of the entire process and its inner workings.
This PR adds more context.

max-moser · 2026-07-31T17:34:40Z

+    This section assumes some familiarity with the creation of Invenio modules.
+
+The module will need to define the appropriate `*.{variables,overrides}` files in the structure that is expected by `semantic-ui-less`.
+See [the file structure in `invenio-app-rdm`](https://github.com/inveniosoftware/invenio-app-rdm/tree/v13.1.2/invenio_app_rdm/theme/assets/semantic-ui/less/invenio_app_rdm/theme) for an example.


I'll update the URLs to v14 tags after we release, so that I can point to pyproject.toml instead of setup.cfg.

We could point to master, and mention it, so then files are always up-to-date when the reader will check them. WDYT?
Pointing to tag might lead to outdated files at some point in the future.

If we want to keep the tag, we should add a link in the Release Management guide to update such link at each release.

I'm fine with just tagging master on a per-file basis, as the general structure regarding the frontend assets hasn't changed in a long time now; but if we're linking to individual lines, I'd prefer pointing to a tag or commit as even a simple reformat could mess the link up.

I guess here, just pointing to files rather than lines in those files is fine, so I'll point it to master 🙂

max-moser · 2026-07-31T18:07:40Z

Current state:

@ntarocco I suppose the "Providing your own theme" section and subsections should be split out into a "how to" section, what do you think?

ntarocco

Thank you very much for rewriting this part!

ntarocco · 2026-08-02T09:44:37Z

+    This section assumes some familiarity with the creation of Invenio modules.
+
+The module will need to define the appropriate `*.{variables,overrides}` files in the structure that is expected by `semantic-ui-less`.
+See [the file structure in `invenio-app-rdm`](https://github.com/inveniosoftware/invenio-app-rdm/tree/v13.1.2/invenio_app_rdm/theme/assets/semantic-ui/less/invenio_app_rdm/theme) for an example.


We could point to master, and mention it, so then files are always up-to-date when the reader will check them. WDYT?
Pointing to tag might lead to outdated files at some point in the future.

ntarocco · 2026-08-02T09:45:06Z

+For the theme to become available to the frontend build under the desired name, you'll need to specify an appropriate *alias* in a `WebpackThemeBundle`, typically in `webpack.py`.
+Just like the alias [`themes/rdm` in `invenio-app-rdm`](https://github.com/inveniosoftware/invenio-app-rdm/blob/v13.1.2/invenio_app_rdm/theme/webpack.py#L73).
+
+Don't forget to register this `WebpackThemeBundle` for the `invenio_assets.webpack` entrypoint group.


Can we also add a link here to show an example?

ntarocco · 2026-08-02T09:45:55Z

+
+Don't forget to register this `WebpackThemeBundle` for the `invenio_assets.webpack` entrypoint group.
+
+In the likely case you want to change the theme's inheritance hierarchy (e.g. add your own theme between the `Invenio App RDM theme` and `Site (your site)` in the [hierarchy described above](#theme-inheritance)), you'll also need to provide your own `theme.less` file.


Likely, or Unlikely?

I'd say likely; at least in the case of Invenio-Theme-TUW, I've added the rdm theme as a step in the hierarchy.
While it's a bit more wasteful (w.r.t. unused CSS rules and thus file sizes), it makes my life quite a bit easier because new InvenioRDM styling gets chased automatically 😄

I'll add that as an explainer!

ntarocco · 2026-08-02T09:50:21Z

I suppose the "Providing your own theme" section and subsections should be split out into a "how to" section, what do you think?

It probably makes sense, because it is indeed more a how-to rather than only internals explanation. It could be part of the existing Change styling part, with a reference + link to the internalssection.
@fenekku opinions?

max-moser · 2026-08-03T11:47:58Z

It could be part of the existing Change styling part

I was actually even considering a new file, to emphasize that instance styling is really something different from themes (and more involved).
Right now we just say once that we differentiate, but then start muddling the concepts a bit again.

My suggestion would be to:

rename the currently existing operate/customize/look-and-feel/theme.md to .../instance-styling.md
add operate/custom/look-and-feel/theme.md with the how-to for creating your own theme (package)

I'm not 100% happy with the placement of the proposed new theme.md under operate/ ("operate an instance"), since this is actually not scoped to a single instance but multiple.
Perhaps it would be better kept somewhere like in "maintain and develop", but the pages there are all just overviews and not how-to pages.

That's just a suggestion though and I don't have a very strong opinion on this, so if you would prefer it to be part of the "styling" how-to, then I'll just add it there @ntarocco 🙂

* previously, the section already contained a few snippets of information, but not really enough to convey a good overview of the entire process and its inner workings Co-authored-by: Nicola <nico@nicolat.org>

max-moser · 2026-08-03T15:44:51Z

Updated the section about how Semantic UI themes get loaded in InvenioRDM, and added a summary of the involved files:

ntarocco · 2026-08-17T12:28:12Z

My suggestion would be to:

* rename the currently existing `operate/customize/look-and-feel/theme.md` to `.../instance-styling.md`

* add `operate/custom/look-and-feel/theme.md` with the how-to for creating your own theme (package)

The issue with renaming files is that we might break existing links. Are we OK with that?

@fenekku any opinion on Max ideas above?

max-moser commented Jul 31, 2026

View reviewed changes

max-moser force-pushed the mm/theming-info branch from 1eff9f7 to f1587c0 Compare July 31, 2026 18:04

ntarocco reviewed Aug 2, 2026

View reviewed changes

max-moser force-pushed the mm/theming-info branch from f1587c0 to 4ab0eb2 Compare August 3, 2026 11:20

theming: provide more information about theming and styling

1951175

* previously, the section already contained a few snippets of information, but not really enough to convey a good overview of the entire process and its inner workings Co-authored-by: Nicola <nico@nicolat.org>

max-moser force-pushed the mm/theming-info branch from 50f4775 to 1951175 Compare August 3, 2026 15:43

max-moser marked this pull request as ready for review August 3, 2026 15:44


		Don't forget to register this `WebpackThemeBundle` for the `invenio_assets.webpack` entrypoint group.

		In the likely case you want to change the theme's inheritance hierarchy (e.g. add your own theme between the `Invenio App RDM theme` and `Site (your site)` in the [hierarchy described above](#theme-inheritance)), you'll also need to provide your own `theme.less` file.

Uh oh!

Conversation

max-moser commented Jul 31, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

max-moser commented Jul 31, 2026

Uh oh!

ntarocco left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ntarocco commented Aug 2, 2026

Uh oh!

max-moser commented Aug 3, 2026

Uh oh!

max-moser commented Aug 3, 2026

Uh oh!

ntarocco commented Aug 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants