Restructure Classic UI / Theming Chapter

[MrTango]

Links of affected pages in Plone Documentation, if any.

• https://6.docs.plone.org/classic-ui/theming/index.html

Description

The sub Chapters like we have them in the trainings, is not help full here. It will lead to not knowing where to put information and having them in more than one place.

I suggest we keep it as flat as possible in this reference documentation.
For now is see chapters like this:

On index page, explain in short the 3 ways of theming.

• Change Logo & Favicon
• Custom CSS TTW
• CSS Variables
  (Custom Properties)
• Creating Theme Packages
  'only the creating part (plonecli), not to much details, reference training for details'

  Custom Barceloneta Theme

  Custom Diazo Theme

  Custom Theme from scatch

• SCSS Structure
• Color modes

[stevepiercy]

@MrTango does this issue supersede #1286, and should the other be closed?

I'll try to get you in Discord to get more details.

[kcm5474]

This would be a good idea. Also providing download links to some example basic custom theme files within the chapter would be helpful to provide reference to newcomers as to what an example of a finished theme should look like. The current Theme "downloads" on the Plone website are just images with no theme files available: https://plone.org/download/theme/ , and the themes I did find online for free were outdated or otherwise incorrect, and did not seem to properly target the elements currently in Plone 6 classic UI.

[stevepiercy]

I closed #1286 as this issue supersedes it.

It doesn't make sense to move around empty and incomplete topics. Let's discuss in the @plone/classicui-team meeting this week, as this has been a long-standing issue. We need to determine the long-term goals of how to structure Theming Classic UI.

Here's the current state, and short-term recommendations.

Theming of Classic UI - Currently only an index and table of contents.

• Classic UI theming based on Barceloneta - Complete
• Classic UI theming with Diazo - Empty. Recommend (1) update link on that page to this issue, (2) create a new issue for that page alone, and (3) update this issue's description to point to (2).
• Classic UI theming from scratch - Only an outline, incomplete. Same recommendations as Classic UI theming with Diazo.
• Through-the-web (TTW) theme customization - Only an outline, incomplete. Same recommendations as Classic UI theming with Diazo.
• Color modes - Complete.

[stevepiercy]

@plone/classicui-team here's a revised issue description. It is not clear to me what @MrTango actually intended, partly due to the strange markup that rendered in a confusing manner, and I don't see clear actionable items that together will result in a comprehensive and comprensible "Classic UI Theming" documentation story. We have several separate pages under the Classic UI navigation that mention "theme" or "theming" in their content that were omitted in the original description, too. Please review and comment. We will discuss at the next Classic UI Team meeting. Thank you!

---

Description

The sub-chapters structure under Theming of Classic UI—which are similar to those in Plone 6 Classic UI Theming—is not helpful here. It will lead to not knowing where to put information and it will spread across multiple locations.

We should create new files with the following topics under Classic UI. We could prefix each file's title with "Theming: ", sensibly group them together in the navigation, and name them theming-* to help editors of documentation.

Topics for documentation

• Changing theme settings TTW - Logo, favicon, a few CSS, and downloading and tweaking and reuploading a theme
• CSS variables - custom properties (reference)
• Theming add-on (source https://6.docs.plone.org/classic-ui/theming/barceloneta.html)
  • Why choose one of the following methods over the others?
  • Barceloneta
  • Diazo
  • from scratch, but with minimal info
• SCSS structure (reference)
• Color modes (how-to) (Source https://6.docs.plone.org/classic-ui/theming/color-mode.html)

Questions

1. Is Layers part of this discussion? Nope.
2. Is Mockup and Patternslib part of this discussion? Nope.
3. Should Recipes be merged into one of the foregoing topics, such as CSS variables? Nope. Will become a collection of how-to guides, not specifically theming.
4. We recently added Static resources to the documentation. Is this part of the restructuring discussion? Sort of, it should be a "See Also" from theming.
5. What are the URLs or authoritative content sources for each of the topics in the revised Description?

Deliverables

• Create an outline of the new file names, their titles, and sources of content. Example:
  • theming-color-modes.md
  • "Theming: color modes"
  • Color modes
• Create a new issue for each of the new files. Reference each issue to this issue.
• Create a new empty file for each issue.
• Create a WIP PR for each new empty file. Reference each PR to this issue.
• Populate each file with content.
• When each WIP PR has sufficient content, merge it.

I can do most of these items, if not all, but I'll need a lot of support from the technical knowledge experts.

---

Finally, I updated the links in 4 documentation pages to point to this issue from the closed issue.

[jensens]

Is Layers part of this discussion?

Layers is a general concept not solely related to theming. It is valid for any type of view, even RestAPI endpoints.

[stevepiercy]

From the Classic UI meeting yesterday, we sorted out the content.

Page title	File name	Type	Content
Change theme settings TTW	theming/settings-ttw.md	how-to	Logo, favicon, a few CSS, and downloading and tweaking and reuploading a theme
Create a theme add-on	theming/create-add-on.md	how-to	https://6.docs.plone.org/classic-ui/theming/barceloneta.html and How to choose one of the following methods over the others? Barceloneta; Diazo; from scratch, but with minimal info
Color modes	theming/color-modes.md	how-to	https://6.docs.plone.org/classic-ui/theming/color-mode.html
CSS custom properties	theming/css-custom-properties.md	reference	https://6.docs.plone.org/classic-ui/theming/barceloneta.html#default-variables-and-properties and https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
SCSS structure	theming/scss-structure.md	reference	https://6.docs.plone.org/classic-ui/theming/barceloneta.html#theme-structure

These 5 files will replace the entire folder under classic-ui/theming, except that index.md will now follow the example of Volto Theming to better align with the Diátaxis Framework.

Note that how-to and reference guides are currently located in the same directory, both on the file system and presentation. That is OK in the Diátaxis Framework. It is possible that each major topic, such as Classic UI or Volto (this was started in Volto's Conceptual guides), may have its own cluster of documentation. The first step is to structure a page's content to fall into one of the four Diátaxis categories. Later we can reorganize them into on of the four appropriate guides within a major topc, if that is practical. I struggled to explain this concept last night. Edit, no longer relevant, per feedback from @petschki.

@1letter @jensens @MrTango @petschki @yurj @thet would you please take a moment and give a thumbs up or down on this comment, along with any corrections? Thank you for your collaboration!

[petschki]

I'd keep a Theming folder inside Classic UI with those files ... this then is the same like the Volto/Theming folder structure

[stevepiercy]

@petschki at first I thought that flattening the structure would be more important, but I think your suggestion makes more sense, looking at what we did in Volto. I've edited the table and my comment. Thanks!