Merge branch '6.0' into dev-guide-create-a-backend-add-on

docs/_inc/_install-browser-reqs-classic-ui.md

@@ -0,0 +1,16 @@
+You can view the list of supported browsers for Classic UI at [Browserslist](https://browsersl.ist/#q=%3E%3D+0.5%25%0Alast+2+major+versions%0Anot+dead%0AChrome+%3E%3D+60%0AFirefox+%3E%3D+60%0AFirefox+ESR%0AiOS+%3E%3D+12%0ASafari+%3E%3D+12%0Anot+Explorer+%3C%3D+11).
+
+The supported web browsers for Classic UI are set according to [Bootstrap](https://getbootstrap.com/docs/5.3/getting-started/browsers-devices/#supported-browsers).
+The following code snippet is the [browserslist configuration for Bootstrap 5.3.3](https://github.com/twbs/bootstrap/blob/v5.3.3/.browserslistrc).
+
+```shell
+>= 0.5%
+last 2 major versions
+not dead
+Chrome >= 60
+Firefox >= 60
+Firefox ESR
+iOS >= 12
+Safari >= 12
+not Explorer <= 11
+```

docs/_inc/_install-browser-reqs-volto.md

@@ -0,0 +1,10 @@
+You can view the list of supported browsers for Volto at [Browserslist](https://browsersl.ist/#q=%3E1%25%0Alast+4+versions%0AFirefox+ESR%0Anot+dead).
+
+These browsers are set according to the `browserslist` key in Volto's [`package.json`](https://github.com/plone/volto/blob/1aff8d0451f5cb375ca9f5afe9b2b72a0555afd8/packages/volto/package.json#L170-L176) file, whose content is below.
+
+```shell
+>1%
+last 4 versions
+Firefox ESR
+not dead
+```

docs/_inc/_install-pillow.md

@@ -1,5 +1,5 @@
 ``````{note}
-After generating a project, then running `make install`, if you see an error message `ERROR: Failed building wheel for Pillow`, then you need to install Pillow's dependencies.
+After generating a project, then running `make install`, if you see an error message `ERROR: Failed building wheel for Pillow` or `The headers or library files could not be found for jpeg, a required dependency when compiling Pillow from source.`, then you need to install Pillow's dependencies.
 
 `````{tab-set}
 
@@ -11,7 +11,7 @@ brew install zlib libjpeg
 
 ````{tab-item} Linux
 ```shell
-apt-get zlib libjpeg
+apt install zlib1g-dev libjpeg8-dev
 ```
 ````
 `````

docs/_inc/_install-pipx.md

@@ -0,0 +1,12 @@
+Install {term}`pipx` for your active Python, and ensure it is on your `$PATH`.
+Carefully read the console output for further instructions, and follow them, if needed.
+
+```shell
+python3 -m pip install pipx
+pipx ensurepath
+```
+
+```{seealso}
+-   [Install `pipx` as a Standalone Tool](https://realpython.com/python-pipx/#install-pipx-as-a-standalone-tool)
+-   [Configure `pipx` Before the First Run](https://realpython.com/python-pipx/#configure-pipx-before-the-first-run)
+```

docs/_inc/_install-python-plone60.md

@@ -1,6 +1,9 @@
 Installing Python is beyond the scope of this documentation.
 However, it is recommended to use a Python version manager, {term}`pyenv`, that allows you to install multiple versions of Python on your development environment without destroying your system's Python.
-% TODO: uncomment this line after upgrading to plone-sphinx-theme and latest Sphinx which supports replacements inside includes.
-% Plone requires Python version {SUPPORTED_PYTHON_VERSIONS_PLONE60}.
 
-Plone 6.0 requires Python version 3.8, 3.9, 3.10, 3.11, or 3.12.
+Plone 6.0 requires Python version {{SUPPORTED_PYTHON_VERSIONS_PLONE60}}.
+
+```{warning}
+Do not create or activate a Python virtual environment at this time.
+The instructions below will create one.
+```

docs/_inc/_install-python-plone61.md

@@ -1,6 +1,9 @@
 Installing Python is beyond the scope of this documentation.
 However, it is recommended to use a Python version manager, {term}`pyenv`, that allows you to install multiple versions of Python on your development environment without destroying your system's Python.
-% TODO: uncomment this line after upgrading to plone-sphinx-theme and latest Sphinx which supports replacements inside includes.
-% Plone requires Python version {SUPPORTED_PYTHON_VERSIONS_PLONE61}.
 
-Plone 6.1 requires Python version 3.10, 3.11, or 3.12.
+Plone 6.1 requires Python version {{SUPPORTED_PYTHON_VERSIONS_PLONE61}}.
+
+```{warning}
+Do not create or activate a Python virtual environment at this time.
+The instructions below will create one.
+```

docs/admin-guide/install-buildout.md

@@ -22,11 +22,18 @@ For other installation options, see {ref}`get-started-install-label`.
 
 (install-buildout-prerequisites)=
 
+
+## Supported web browsers
+
+```{include} /_inc/_install-browser-reqs-classic-ui.md
+```
+
+
 ## Prerequisites for installation
 
--   For Plone 6.0, Python {SUPPORTED_PYTHON_VERSIONS_PLONE60}
+-   For Plone 6.0, Python {{SUPPORTED_PYTHON_VERSIONS_PLONE60}}
 % TODO: These instructions install Plone 6.0.x. Uncomment next line and change the subsequent include when Plone 6.1 is released and "latest".
-% -   For Plone 6.1, Python {SUPPORTED_PYTHON_VERSIONS_PLONE61}
+% -   For Plone 6.1, Python {{SUPPORTED_PYTHON_VERSIONS_PLONE61}}
 
 
 ### Python

docs/admin-guide/install-pip.md

@@ -20,13 +20,20 @@ It provides a basic installation without many additional tools to help with deve
 For other installation options, see {ref}`get-started-install-label`.
 ```
 
+
+## Supported web browsers
+
+```{include} /_inc/_install-browser-reqs-classic-ui.md
+```
+
+
 (install-pip-prerequisites)=
 
 ## Prerequisites for installation
 
--   For Plone 6.0, Python {SUPPORTED_PYTHON_VERSIONS_PLONE60}
+-   For Plone 6.0, Python {{SUPPORTED_PYTHON_VERSIONS_PLONE60}}
 % TODO: These instructions install Plone 6.0.x. Uncomment next line and change the subsequent include when Plone 6.1 is released and "latest".
-% -   For Plone 6.1, Python {SUPPORTED_PYTHON_VERSIONS_PLONE61}
+% -   For Plone 6.1, Python {{SUPPORTED_PYTHON_VERSIONS_PLONE61}}
 
 
 ### Python

docs/backend/upgrading/version-specific-migration/p4x-to-p5x-upgrade.md

@@ -26,7 +26,7 @@ To upgrade add-ons to Plone 5, see also {doc}`upgrade-addons-to-50`.
 -   Always upgrade from the latest version of 4.x to the latest version of 5.x (4.3.20 to 5.2.9 at the time of writing).
     This will resolve many migration-specific issues.
 -   If you have problems, ask for help on https://community.plone.org.
--   The talk _How to upgrade sites to Plone 5_ has a [video](https://www.youtube.com/watch?t=1m17s&v=bQ-IpO-7F00&feature=youtu.be) and [slides](https://www.slideshare.net/slideshow/upgrade-to-plone-5/54040952).
+-   The talk _How to upgrade sites to Plone 5_ has a [video](https://www.youtube-nocookie.com/embed/bQ-IpO-7F00?privacy_mode=1&t=77) and [slides](https://www.slideshare.net/slideshow/upgrade-to-plone-5/54040952).
 
 
 (upgrading-plone-4.x-to-5.0-changes-due-to-implemented-plips-label)=
@@ -448,7 +448,7 @@ The value you use for this CSS rule should identify one of the fontello icons in
 
 It is not possible at this time to set an icon for your add-on package control panels without including CSS in your package.
 
-For documentation on how to use it in your own add-ons see {doc}`training:mastering-plone-5/registry`.
+For documentation on how to use it in your own add-ons see {doc}`training-2023:mastering-plone-5/registry`.
 
 
 ### Properties

docs/backend/upgrading/version-specific-migration/upgrade-to-60.md

@@ -212,7 +212,7 @@ Add-on authors may want to use this to get, create, or delete relations.
 Mockup contains the source of most Classic UI Plone JavaScript.
 The compiled version is in `plone.staticresources`.
 
-Mockup is now based on [Patternslib 4](https://patternslib.com/).
+Mockup is now based on [Patternslib 9](https://patternslib.com/).
 It uses ES6 module imports instead of RequireJS.
 Add-ons for Classic UI Plone that use JavaScript should be updated to use ES6 modules as well.
 

docs/backend/upgrading/version-specific-migration/upgrade-to-61.md

@@ -32,9 +32,41 @@ To upgrade your plugin implementation to TinyMCE 7, see the [upgrade guides](htt
 
 ### Enable the TinyMCE accordion plugin
 
-1.  Go to the {guilabel}`Site Setup > General > TinyMCE` control panel to manage TinyMCE settings.
-1.  Under the {guilabel}`Plugins and Toolbar` tab, check {guilabel}`accordion` to enable the accordion plugin.
-1.  Under the same tab, add a menu entry `accordion` for TinyMCE in the control panel by editing the `items` key as shown.
+1.  Install the add-on [`collective.outputfilters.tinymceaccordion`](https://pypi.org/project/collective.outputfilters.tinymceaccordion/) to use an output filter that transforms the TinyMCE markup to valid HTML markup for the Bootstrap 5 accordion.
+    Install via either pip or buildout.
+
+    -   Install using pip.
+
+        ```shell
+        pip install collective.outputfilters.tinymceaccordion   
+        ```
+
+    -   Configure your local buildout file.
+
+        ```cfg
+        [instance]
+        eggs += collective.outputfilters.tinymceaccordion
+        ```
+
+        Then run the command to install.
+
+        ```shell
+        bin/buildout
+        ```
+
+1.  Start your Plone instance.
+
+    ```shell
+    bin/instance fg
+    ```
+
+1.  Complete installation of the add-on by navigating to {menuselection}`Site Setup --> General --> Add-ons`, then clicking {guilabel}`Install` for `collective.outputfilters.tinymceaccordion`.
+
+1.  Go to the {menuselection}`Site Setup --> General --> TinyMCE` control panel to manage TinyMCE settings.
+
+1.  Under the {menuselection}`Plugins and Toolbar` tab, if not already checked, check {guilabel}`accordion` to enable the accordion plugin.
+
+1.  Under the same tab, edit the `insert` menu by editing its `items` key as shown.
 
     ```json
     {
@@ -46,21 +78,17 @@ To upgrade your plugin implementation to TinyMCE 7, see the [upgrade guides](htt
     ```
 
 1.  Click the {guilabel}`Save` button to save your settings.
-1.  In the {guilabel}`Security > HTML filtering` control panel, add two new tags to {guilabel}`Valid tags`.
 
-    -   `summary`
+1.  In the {menuselection}`Security --> HTML filtering` control panel, ensure that you have the following tags under {guilabel}`Valid tags`.
+
+    -   `button`
     -   `details`
+    -   `summary`
 
-1.  Also in the {guilabel}`Security > HTML filtering` control panel, add a new attribute to {guilabel}`Custom attributes`.
+1.  Also in the {menuselection}`Security --> HTML filtering` control panel, add a new attribute to {guilabel}`Custom attributes`, if not already present.
 
     -   `open`
 
-1.  For a transform to valid markup of the Bootstrap 5 accordion, use an output filter.
-
-    ```{seealso}
-    -   [Addon collective.outputfilters.tinymceaccordion](https://github.com/collective/collective.outputfilters.tinymceaccordion)
-    ```
-
 
 ## `z3c.form` and `plone.app.z3cform`
 

docs/classic-ui/index.md

@@ -34,6 +34,7 @@ static-resources
 template-global-variables
 templates
 theming/index
+tinymce-customization
 viewlets
 views
 whatsnew

docs/classic-ui/tinymce-customization.md

@@ -0,0 +1,87 @@
+---
+myst:
+  html_meta:
+    "description": "TinyMCE customization in Plone 6"
+    "property=og:description": "TinyMCE customization in Plone 6"
+    "property=og:title": "TinyMCE customization in Plone 6"
+    "keywords": "Plone 6, Classic UI, Bootstrap 5, TinyMCE, customization"
+---
+
+(classic-ui-tinymce-customization-label)=
+
+# TinyMCE customization
+
+This chapter is a developer reference manual for customizing {term}`TinyMCE`.
+
+
+## Customize {menuselection}`Format` menu
+
+There are several options to customize TinyMCE's {menuselection}`Format --> Formats` menu.
+
+The first two options use TinyMCE's [`formats` JSON configuration](https://www.tiny.cloud/docs/tinymce/latest/content-formatting/).
+They are less complicated to implement than the third option.
+
+
+### Add-on GenericSetup configuration file
+
+This option is best for system administrators and developers who write their own add-ons to ease reproducibility.
+
+You can add a GenericSetup configuration file to your add-on, such as {file}`profiles/default/registry/tinymce.xml`, with the following content.
+
+```xml
+<registry>
+  <records interface="plone.base.interfaces.controlpanel.ITinyMCESchema"
+            prefix="plone">
+    <value key="formats"
+           purge="true"
+        >{
+        "myformat": {
+            "block": "div",
+            "classes": "my-css-classes"
+        }
+    }</value>
+  </records>
+</registry>
+```
+
+
+### Edit the `Formats` option in the TinyMCE control panel
+
+This option is good for quick edits, but is not as reproducible as the GenericSetup option.
+
+You can manually customize the `Formats` value through-the-web in the TinyMCE control panel.
+
+1.  Navigate to {menuselection}`Site Setup --> TinyMCE --> Default`, or append `@@tinymce-controlpanel` to the root of your website in your browser's location bar.
+1.  Scroll down to {guilabel}`Formats`, and edit the JSON configuration.
+1.  Click the {guilabel}`Save` button.
+
+
+
+### Inject formats with files named {file}`tinymce-formats.css`
+
+This option is more complex to implement than the previous options.
+
+In Plone 6, TinyMCE has a special logic that automatically reads registered files named {file}`tinymce-formats.css` and adds the CSS classes defined in those files to TinyMCE's {menuselection}`Format --> Formats` menu by using the [`importcss_file_filter` option](https://www.tiny.cloud/docs/tinymce/latest/importcss/#importcss_file_filter).
+
+To add custom formats, you can provide your own files.
+
+1.  Name the file {file}`tinymce-formats.css`.
+1.  Register the file as a resource in your Plone site.
+1.  Include the file in the TinyMCE control panel in the textarea input {guilabel}`Choose the CSS used in WYSIWYG Editor Area`.
+    1.  Navigate to {menuselection}`Site Setup --> TinyMCE --> Default`, or append `@@tinymce-controlpanel` to the root of your website in your browser's location bar.
+    1.  Scroll down to {guilabel}`Choose the CSS used in WYSIWYG Editor Area`.
+
+CSS styles defined in this file will automatically be added to the top level of TinyMCE's {menuselection}`Format --> Formats` menu.
+
+
+## Remove imported formats
+
+Plone 6 Classic UI ships with the Barceloneta theme which includes two custom formats, `highlight-inline` and `p.highlight-paragraph`, in the TinyMCE {menuselection}`Format --> Formats` menu.
+You can remove these formats through the TinyMCE control panel.
+
+1.  Navigate to {menuselection}`Site Setup --> TinyMCE --> Default`, or append `@@tinymce-controlpanel` to the root of your website in your browser's location bar.
+1.  Scroll down to {guilabel}`Choose the CSS used in WYSIWYG Editor Area`.
+1.  Remove the entry `++theme++barceloneta/tinymce/tinymce-formats.css`.
+1.  Click the {guilabel}`Save` button.
+
+Once removed, the custom formats will no longer appear in the menu.

docs/classic-ui/viewlets.md

@@ -209,7 +209,7 @@ The following Python code example, such as in a file {file}`viewlets.py`, extend
 ```{todo}
 The following Facebook like viewlet example is obsolete (note that links use `http`) and needs to be replaced with a modern one.
 The concept is valid, but the code will not actually work with Facebook.
-For a somewhat more recent example, see {doc}`training:mastering-plone-5/viewlets_1` in the Master Plone 5 training.
+For a somewhat more recent example, see {doc}`training-2023:mastering-plone-5/viewlets_1` in the Master Plone 5 training.
 ```
 
 ```python

docs/classic-ui/views.md

@@ -663,9 +663,9 @@ This way you will also have a test for the generated view.
 
 The Mastering Plone 5 Training has several chapters on views.
 
--   {doc}`training:mastering-plone-5/views_1`
--   {doc}`training:mastering-plone-5/views_2`
--   {doc}`training:mastering-plone-5/views_3`
+-   {doc}`training-2023:mastering-plone-5/views_1`
+-   {doc}`training-2023:mastering-plone-5/views_2`
+-   {doc}`training-2023:mastering-plone-5/views_3`
 
 
 (classic-ui-anatomy-of-a-view-label)=

docs/conceptual-guides/index.md

@@ -19,6 +19,7 @@ choose-user-interface
 compare-buildout-pip
 distributions
 package-management
+package-dependencies
 make-build-backend-walk-through
 components
 ```