Skip to content

Commit 5033333

Browse files
jensensjensens
authored
Merge branch '6-dev' into 6-dev--module-federation
2 parents 08b9534 + 24e95ad commit 5033333

33 files changed

+1468
-285
lines changed

‎docs/_static/custom.css

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,14 @@ div.section {
106106
margin-bottom: 5rem;
107107
}
108108

109+
div.section div.section {
110+
margin-bottom: 5rem;
111+
}
112+
113+
div.section div.section div.section {
114+
margin-bottom: 2rem;
115+
}
116+
109117
/* admonitions */
110118
.admonition {
111119
border-radius: 0;
@@ -155,6 +163,11 @@ div.admonition.admonition-todo>.admonition-title::before {
155163
display: none;
156164
}
157165

166+
/* admonition margin */
167+
.admonition.margin ul,
168+
.admonition.margin ol {
169+
padding-left: 1rem;
170+
}
158171

159172
.topic {
160173
padding: 1.5em 1em .5em 1em;

‎docs/_static/illustration/pm2.png

127 KB
Loading

‎docs/_templates/layout.html

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{% extends "sphinx_book_theme/layout.html" %}
2+
{%- block extrahead %}
3+
{{ super() }}
4+
<!-- Matomo Tag Manager -->
5+
<script>
6+
var _mtm = window._mtm = window._mtm || [];
7+
_mtm.push({'mtm.startTime': (new Date().getTime()), 'event': 'mtm.Start'});
8+
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
9+
g.async=true; g.src='https://stats.plone.org/js/container_d3bIlNkY.js'; s.parentNode.insertBefore(g,s);
10+
</script>
11+
<!-- End Matomo Tag Manager -->
12+
{% endblock %}
13+
14+
15+
{% block body_tag %}
16+
<body data-spy="scroll" data-target="#bd-toc-nav" data-offset="100">
17+
{%- endblock %}

‎docs/backend/index.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,18 @@
22
html_meta:
33
"description": ""
44
"property=og:description": ""
5-
"property=og:title": ""
6-
"keywords": ""
5+
"property=og:title": "Backend"
6+
"keywords": "Plone 6, Volto, Classic UI, frontend, backend, plone.restapi, plone.api"
77
---
88

99
(backend-index-label)=
1010

1111
# Backend
1212

13+
```{todo}
14+
Insert introduction here.
15+
```
16+
1317
```{toctree}
1418
:maxdepth: 2
1519
control-panels

‎docs/backend/upgrading/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,4 +16,5 @@ html_meta:
1616
:hidden:
1717
1818
v60
19+
migrate-to-volto
1920
```

‎docs/backend/upgrading/migrate-to-volto.md

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
---
2+
html_meta:
3+
"description": "Migrate to Volto"
4+
"property=og:description": "Migrate to Volto"
5+
"property=og:title": "Migrate to Volto"
6+
"keywords": "Migrating, Upgrading, Plone 6, Volto"
7+
---
8+
9+
(backend-migrate-to-volto-label)=
10+
11+
# Migrate to Volto
12+
13+
Plone 6 comes with a new default frontend called {term}`Volto`.
14+
Volto is written in React and uses {py:mod}`plone.restapi` to communicate with the backend.
15+
16+
When creating a new Plone 6 site, you may choose between frontends.
17+
18+
- Volto - {guilabel}`Create a new Plone site`, the default option
19+
- {term}`Classic UI` - {guilabel}`Create Classic Plone site`
20+
- {guilabel}`Advanced`
21+
22+
This choice is presented because there are some non-trivial differences between their configurations.
23+
This document discusses these differences.
24+
It also informs administrators and developers of how to migrate their existing Plone 6 site with Classic UI to instead become compatible with Volto for its frontend.
25+
26+
```{important}
27+
As a pre-requisite, your Plone site must be [upgraded to Plone 6](v60) before migrating to Volto for the frontend.
28+
```
29+
30+
Plone provides a form `/@@migrate_to_volto` that allows you to run all the required changes to your existing site to make it compatible with Volto.
31+
32+
You can access this form in the browser when you are logged in as an administrator.
33+
Open `http://localhost:8080/Plone/@@migrate_to_volto`, where `localhost` is your hostname, `8080` is the port on which Plone runs, and `Plone` is the name of the Plone instance.
34+
35+
Additionally, after upgrading an existing site to Plone 6 (see {doc}`v60`), a message will appear, **You can prepare your site for Volto, the default frontend of Plone 6!**, with a link to that form.
36+
37+
```{warning}
38+
Test all migrations thoroughly before applying them on a production environment!
39+
40+
A site that is made compatible with Volto will be accessible with Plone Classic UI, but it will behave differently.
41+
For example, editors can only effectively work with the content using Volto because HTML is no longer editable in the TinyMCE editor used in Classic UI.
42+
```
43+
44+
The required steps are:
45+
46+
1. **Install the packages {py:mod}`plone.volto` and {py:mod}`plone.restapi`.**
47+
48+
{py:mod}`plone.restapi` is the RESTful API for Plone that allows the frontend Volto to communicate with the backend.
49+
{py:mod}`plone.volto` configures Plone to work with Volto, the new default frontend for Plone 6.
50+
51+
1. **Migrate RichText fields to Volto blocks**
52+
53+
Volto has a new editor called Slate, whereas Classic UI uses TinyMCE.
54+
This step converts the HTML stored in RichText fields to text blocks, allowing you to edit them in Volto.
55+
Images, links, and most kinds of HTML formatting are preserved.
56+
57+
For this you need to have `blocks-conversion-tool` running on an accessible URL.
58+
The easiest way to have that running on your machine is to use Docker:
59+
60+
```shell
61+
docker run -it -p 5000:5000 plone/blocks-conversion-tool:latest
62+
```
63+
64+
For more options read https://github.com/plone/blocks-conversion-tool.
65+
66+
1. **Pages, News Items, and Events are made folderish**
67+
68+
That means these types can contain other content such as Images or other Pages.
69+
When you create a new site in Plone 6, this setting is also applied automatically.
70+
But existing content remains non-folderish until this step is run.
71+
72+
1. **Turn folders into folderish pages**
73+
74+
In Volto adding Folders is disabled by default.
75+
Instead folderish pages are used to create folder structures.
76+
This step turns all folders into folderish pages.
77+
If the folder shows a listing of the content, an appropriate listing block will be added.
78+
If the folder shows a default page, then it will be handled in the next step.
79+
You can re-enable Folders by checking the box {guilabel}`Implicitly addable?` in ``/portal_types/Folder/manage_propertiesForm``.
80+
81+
1. **Default Pages of Folders are merged with the Folderish Pages that replace the Folder**
82+
83+
Volto does not have a concept of default pages.
84+
Instead folderish pages can show text, a listing of all the content inside that page, or both.
85+
This step takes the content of the default page (such as text or the query of a collection), and adds that to the folderish page that replaces the folder.
86+
Metadata (subjects, author, rights, and so on) and relations are moved to the folderish page.
87+
88+
89+
1. **Collections are migrated to Pages with Listing Blocks**
90+
91+
In Volto adding Collections is disabled by default.
92+
Instead folderish pages with listing blocks are used.
93+
This step turns all collections into folderish pages.
94+
The criteria of the collection are used to configure a listing block in that page.
95+
96+
It is recommended to use the default settings, but you can choose to skip some migration steps in the form.
97+
98+
```{note}
99+
If you are migrating an existing site to Plone 6 using [{py:mod}`collective.exportimport`](https://pypi.org/project/collective.exportimport) and want to use Volto in the new site, then you do not need to use the form `@@migrate_to_volto`.
100+
101+
All the changes documented above can be done efficiently during export and import.
102+
[Read details](https://github.com/collective/collective.exportimport/issues/133).
103+
```

‎docs/backend/upgrading/v60.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,9 @@ The classic integrated frontend which is called "Classic UI" is still available
5555
If you choose to use Classic UI, then do not use the `plone.volto` package.
5656
```
5757

58+
To learn how to modify an existing Plone site to run with Volto, please read {doc}`migrate-to-volto`.
59+
60+
5861
See [PLIP 2703](https://github.com/plone/Products.CMFPlone/issues/2703).
5962

6063

‎docs/conf.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -183,9 +183,9 @@
183183

184184
# -- OpenGraph configuration ----------------------------------
185185

186-
ogp_site_url = "https://docs.plone.org/"
186+
ogp_site_url = "https://6.dev-docs.plone.org/"
187187
ogp_description_length = 200
188-
ogp_image = "https://docs.plone.org/_static/Plone_logo_square.png"
188+
ogp_image = "https://6.dev-docs.plone.org/_static/Plone_logo_square.png"
189189
ogp_site_name = "Plone Documentation"
190190
ogp_type = "website"
191191
ogp_custom_meta_tags = [

‎docs/contributing/index.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
---
22
html_meta:
3-
"description": "Contributing to Plone Documentation"
4-
"property=og:description": "Contributing to Plone Documentation"
5-
"property=og:title": "Contributing to Plone Documentation"
3+
"description": "Contributing to Plone 6 Documentation"
4+
"property=og:description": "Contributing to Plone 6 Documentation"
5+
"property=og:title": "Contributing to Plone 6 Documentation"
66
"keywords": "Plone, Plone Contributor Agreement, License, Code of Conduct"
77
---
88

99
(contributing-index-label)=
1010

11-
# Contributing to Plone Documentation
11+
# Contributing to Documentation
1212

1313
This document describes how to contribute to Plone Documentation.
1414

‎docs/contributing/writing-docs-guide.md

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -215,7 +215,6 @@ This is MyST syntax for term ``{term}`React` ``
215215
This is MyST syntax for term ``{term}`React` ``
216216

217217

218-
219218
##### Glossary terms
220219

221220
Add a term to the {ref}`glossary-label`, located at {file}`/glossary.md`.
@@ -235,6 +234,48 @@ Using {term}`React` makes frontends fun again!
235234
Using {term}`React` makes frontends fun again!
236235

237236

237+
#### Toggle paragraph (Exercise solution / FAQ)
238+
239+
Text snippets can be hidden with the option to show. Wrap it in an `admonition` and add the `class` `toggle`.
240+
241+
`````
242+
````{admonition} f-strings can make your life easier
243+
:class: toggle
244+
245+
To use formatted string literals, begin a string with `f` or `F` before the opening quotation mark or triple quotation mark.
246+
Inside this string, you can write a Python expression between `{` and `}` characters that can refer to variables or literal values.
247+
248+
```{code-block} python
249+
:linenos:
250+
:emphasize-lines: 1, 3
251+
252+
a = 2
253+
print("my 1st line")
254+
print(f"my {a}nd line")
255+
```
256+
````
257+
`````
258+
259+
You can [nest directives](https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#nesting-directives), such as admonitions and code blocks, by ensuring that the backtick-lines corresponding to the outermost directive are longer than the backtick-lines for the inner directives.
260+
261+
This would be rendered as:
262+
263+
````{admonition} f-strings can make your life easier
264+
:class: toggle
265+
266+
To use formatted string literals, begin a string with `f` or `F` before the opening quotation mark or triple quotation mark.
267+
Inside this string, you can write a Python expression between `{` and `}` characters that can refer to variables or literal values.
268+
269+
```{code-block} python
270+
:linenos:
271+
:emphasize-lines: 1, 3
272+
273+
a = 2
274+
print("my 1st line")
275+
print(f"my {a}nd line")
276+
```
277+
````
278+
238279

239280
## Abridged Plone Documentation Styleguide
240281

0 commit comments

Comments
 (0)