Document distributions in the 6.1 upgrade guide.

docs/admin-guide/add-site.md

@@ -0,0 +1,73 @@
+---
+myst:
+  html_meta:
+    "description": "How to add a Plone site to an existing Zope instance"
+    "property=og:description": "How to add a Plone site to an existing Zope instance"
+    "property=og:title": "Add a Plone site"
+    "keywords": "Plone 6, create, add, factory, distributions"
+---
+
+(add-a-plone-site-label)=
+
+# Add a Plone site
+
+This section explains how to add a Plone site to an existing Zope instance.
+It assumes that you have already {doc}`installed </install/index>` and started Plone.
+
+Some installation methods create a Plone site for you already.
+Follow these instructions if you used an installation method that did not do this, or if you need a second Plone site in the same instance for some reason.
+
+```{versionadded} Plone 6.1
+The user interface for creating a new Plone site was changed in Plone 6.1.
+You can access it the same way in Plone 6.0, but the appearance and options are different.
+```
+
+Visit the Plone backend in a web browser.
+Usually it is running at http://localhost:8080/.
+
+The launch screen prompts you to choose one of the available {term}`distributions` to create a new site.
+You can read {doc}`/conceptual-guides/choose-user-interface` to help inform your choice between Volto and Classic UI.
+
+````{card}
+```{image} /backend/upgrading/version-specific-migration/images/distribution-chooser.png
+:alt: Launch screen for choosing a distribution
+:target: /_images/distribution-chooser.png
+```
++++
+_Launch screen for choosing a distribution_
+````
+
+Hover over your choice and click the {guilabel}`Create` button.
+
+Now complete the form with initial configuration for your site.
+You can configure the following settings.
+
+Path Identifier
+:   The ID of the site.
+    This ends up as part of the URL unless hidden by an upstream web server.
+
+Title
+:   The name of the site in the HTML `title` element.
+    This will be shown as part of the title of the browser tab on each page.
+
+Site Description
+:   A brief description that will be served in an HTML `meta` tag.
+
+Site Logo
+:   Upload an image as the main site logo.
+
+Language
+:   The main language of the site.
+
+Timezone
+:   The default timezone setting of the portal.
+
+Finally, click the {guilabel}`Submit` button.
+
+Have fun with your new Plone site!
+
+```{important}
+The launch screen for adding a site is hosted by the Plone backend server.
+Regardless of the frontend you select, you will be redirected to the backend's user interface after you create the site.
+If you select the Volto frontend, you can switch to it by changing the port number in the URL, usually `3000`, and visiting it at http://localhost:3000, for example.
+```

docs/admin-guide/index.md

@@ -29,6 +29,7 @@ install-pip
 :maxdepth: 1
 
 run-plone
+add-site
 configure-zope
 add-ons
 override-core

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

@@ -136,3 +136,44 @@ If you have an existing Plone 5.2 or 6.0 site and you migrate to 6.1, then migra
 -   If the `plone.app.discussion` Python package is _not_ in your setup, but the site has existing comments (discussions), then the migration code stops with an error.
     Apparently you _were_ using comments in your site.
     Add the `plone.app.discussion` package to your dependencies, and run the migration again.
+
+
+## Distributions
+
+Plone 6.1 introduces the concept of a Plone {term}`distribution`.
+A Plone distribution is a Python package that defines specific features, themes, add-ons, and configurations that get activated when creating a Plone site.
+Now it is available in core Plone as the recommended way for {doc}`creating a new Plone site </admin-guide/add-site>`.
+
+```{seealso}
+For more information about distribution concepts, see {doc}`/conceptual-guides/distributions`.
+```
+
+Distributions are optional.
+If your project only uses the `Products.CMFPlone` Python package, you can still create a Plone site in the old way.
+Consider, however, that doing so you will have the following differences when compared to using distributions.
+
+-   The configuration form is simpler and shorter.
+-   The created site has no content, and therefore no {guilabel}`News` or {guilabel}`Events` folders.
+-   You must activate add-ons through the {guilabel}`Add-ons` control panel.
+
+There are a few things you should consider when upgrading a project to, or making an add-on compatible with, Plone 6.1.
+
+-   In general, you don't need to change anything.
+    Your existing site will keep working.
+    But adding a new site may change in the ways described earlier.
+-   Do you want to use the `Products.CMFPlone` package (no distributions), either `plone.volto` or `plone.classicui` (one distribution), or `Plone` (two distributions)?
+-   If your site uses Volto for the frontend, you will already have `plone.volto` as a dependency.
+    This can stay the same.
+-   If your site depends on the `Products.CMFPlone` package without the `Plone` or `plone.volto` packages, then the frontend is Classic UI.
+    This can stay the same, but you may want to depend on `plone.classicui`.
+    With that package you can still create a new site and have the same content as before.
+-   If your site uses the `Plone` package, you will have the two new distributions available.
+    This is fine.
+    If you know you only need `plone.volto` or only need `plone.classicui`, you can switch to only one or the other.
+    You can also limit the options for selecting a distribution by setting the environment variable `ALLOWED_DISTRIBUTIONS` with fewer options.
+    Set `ALLOWED_DISTRIBUTIONS=default` for the distribution targeting the Volto frontend (`plone.volto`).
+    Set `ALLOWED_DISTRIBUTIONS=classic` for the distribution with the Classic UI frontend (`plone.classicui`).
+-   If you switch from `Plone` to `plone.volto` or `plone.classicui`, you might want to install extra core add-ons, for example `plone.app.upgrade` or `plone.app.caching`.
+-   If your add-on is only for Volto, you might want to add `plone.volto` as a dependency.
+-   If your add-on is only for Classic UI, you might want to add `plone.classicui` as a dependency.
+    Note though that `plone.classicui` is not available for Plone 6.0.

docs/conceptual-guides/distributions.md

@@ -0,0 +1,89 @@
+---
+myst:
+  html_meta:
+    "description": "A Plone distribution is a pre-packaged version of Plone that includes specific features, themes, modules, and configurations."
+    "property=og:description": "A Plone distribution is a pre-packaged version of Plone that includes specific features, themes, modules, and configurations."
+    "property=og:title": "Plone distributions"
+    "keywords": "Plone 6, distribution, plone.distribution"
+---
+
+(plone-distributions-label)=
+
+# Plone distributions
+
+```{versionadded} Plone 6.1
+```
+
+A Plone {term}`distribution` is a pre-packaged version of Plone that includes specific features, themes, modules, and configurations.
+It is a convenient way to get a specific type of website up and running quickly, as the distribution includes everything needed to run that type of site.
+
+```{seealso}
+To create your own distribution, see {doc}`/developer-guide/create-a-distribution`.
+```
+
+
+## Built-in distributions
+
+Plone comes with two built-in distributions, which correspond to the two Plone user interfaces.
+
+[`plone.volto`](https://github.com/plone/plone.volto)
+:   Create a Plone site with the Volto frontend.
+
+[`plone.classicui`](https://github.com/plone/plone.classicui) 
+:   Create a Plone site with the Classic UI frontend.
+
+
+## Third-party distributions
+
+You can create your own distributions to suit your needs.
+
+```{seealso}
+For a how-to guide, see {doc}`/developer-guide/create-a-distribution`.
+```
+
+For example, a Plone consulting agency can create a distribution demonstrating its favorite setup for Plone.
+This would contain the add-ons that they usually add in each project, including example content.
+With this, the agency can create a fully configured Plone site filled with content for a potential client.
+
+Alternatively, an agency or implementer can create a distribution for specific project.
+This could create a site with all add-ons activated and configured for this project, including example content, and optionally users and groups.
+During the development phase of a new project, all developers would use this to create a fresh site locally so that everyone has the same configuration and content.
+
+Custom Plone distributions can be distributions for use by others.
+Examples of third-party Plone distributions include:
+
+- [SENAITE](https://www.senaite.com)
+- [Quaive](https://quaive.com/)
+- [Portal Modelo](https://www.interlegis.leg.br/produtos-servicos/portal-modelo/)
+- [Portal Padrão](https://identidade-digital-de-governo-plone.readthedocs.io/en/latest/)
+
+
+## Related packages
+
+The implementation of distributions in the Plone codebase is found in the following Python packages.
+
+-   [`plone.distribution`](https://github.com/plone/plone.distribution) provides the framework for defining distributions.
+-   [`plone.exportimport`](https://github.com/plone/plone.exportimport) imports and exports content, users, and other objects between Plone sites.
+    `plone.distribution` uses it.
+-   [`plone.volto`](https://github.com/plone/plone.volto) is the distribution to create a Plone site with the Volto frontend.
+-   [`plone.classicui`](https://github.com/plone/plone.classicui) is the distribution to create a Plone site with the Classic UI frontend.
+
+```{note}
+For Plone 7, the [Plone roadmap](https://plone.org/why-plone/roadmap) guides development toward a clearer separation between the Classic UI frontend and the core `Products.CMFPlone` backend.
+This means that in Plone 7, `Products.CMFPlone` will have less code and pull in fewer dependencies, whereas `plone.classicui` may have more code and pull in more dependencies.
+This is the direction in which the backend is heading, and the introduction of the `plone.classicui` distribution package is an important step along this path.
+```
+
+## Comparison with other CMSs
+
+Drupal
+:   Drupal has distributions for blogs, e-commerce sites, and intranet portals.
+
+WordPress
+:   WordPress has a similar concept in the form of "WordPress Multisite," which allows users to run multiple websites from a single installation of WordPress.
+
+Joomla
+:   Joomla has a similar concept in the form of "Joomla Templates," which are pre-designed templates for Joomla websites.
+
+TYPO3
+:   TYPO3 has a similar concept in the form of "TYPO3 Distributions," which are pre-configured installations of TYPO3 for specific types of websites.

docs/conceptual-guides/index.md

@@ -16,6 +16,7 @@ This part of the documentation provides explanation of concepts to deepen and br
 :maxdepth: 2
 
 choose-user-interface
+distributions
 package-management
 make-build-backend-walk-through
 ```

docs/conceptual-guides/make-build-backend-walk-through.md

@@ -52,7 +52,7 @@ The command `make build-backend`:
 
 -   Returning to the target `build-dev`:
 
-    -   This generates the `mxdev` files as described above in {ref}`mxdev-usage-overview-label`.
+    -   This generates the `mxdev` files as described above in {ref}`manage-backend-python-packages-label`.
     -   Installs Plone core packages and add-ons from the files generated by `mxdev`.
 
 You can configure your Zope instance as described in the section {doc}`/admin-guide/configure-zope`.

docs/conf.py

@@ -82,15 +82,18 @@
     r"http://127.0.0.1",
     r"http://localhost",
     r"http://yoursite",
-    # Ignore file downloads
+    # Ignore static file downloads
     r"^/_static/",
+    r"^/_images/",
     # Ignore pages that require authentication
     r"https://github.com/orgs/plone/teams/",  # requires auth
     r"https://github.com/plone/documentation/issues/new/choose",  # requires auth
     r"https://github.com/plone/volto/issues/new/choose",  # requires auth
     r"https://opensource.org/",  # requires auth
     # Ignore github.com pages with anchors
     r"https://github.com/.*#.*",
+    # Ignore github.com searches
+    r"https://github.com/search",
     # Ignore other specific anchors
     r"https://coveralls.io/repos/github/plone/plone.restapi/badge.svg\?branch=main",  # plone.restapi
     r"https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors#Identifying_the_issue",