From 9ea421351da21bded5b979a44427c37ccbb19996 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 28 Feb 2024 06:23:38 -0800 Subject: [PATCH 01/15] Improve the Volto home page to serve as a wayfinding page for various Volto audiences --- docs/source/index.md | 37 ++++++++++++++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/docs/source/index.md b/docs/source/index.md index 10318b335e..ce18a26547 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -14,13 +14,44 @@ myst: Volto is a React-based frontend for the [Plone CMS](https://plone.org). It is the default frontend starting with the Plone 6 release. -Volto provides an attractive proposition: integration with the modern frontend development world, access to the huge ecosystem of React libraries and addons, combined with the ability to use the mature Plone CMS backend as a development platform. +Volto provides an attractive proposition: integration with the modern frontend development world, access to the huge ecosystem of React libraries and add-ons, combined with the ability to use the mature Plone CMS backend as a development platform. -Thanks to the use of the Plone REST API, it is fully compatible with Plone's content type framework. But its power comes from the innovative Pastanaga editor, which provides a flexible WYSIWYG editing interfaces based on "blocks". +Thanks to the use of the Plone REST API, it is fully compatible with Plone's content type framework. +But its power comes from the innovative Pastanaga editor, which provides a flexible WYSIWYG editing interface based on "blocks". Thanks to their simplicity and easy access to advanced frontend integration, Volto blocks can provide a fast development experience that reduces developer frustration and improves end-user experience. -To start developing a new Volto project you should have minimal React and modern JavaScript knowledge. Follow the {doc}`plone:install/create-project` guide to bootstrap a new Volto project and start hacking! + +## Get started + +Choose from the following sections to begin your journey with Volto. + + +### Contributors + +A contributor is someone who writes code or documentation for the Volto core packages. + +- {doc}`plone:contributing/first-time` is for people who have yet to make a contribution to Plone, Volto, or open source software. +- {doc}`plone:contributing/index` is for people who have not yet signed the Plone Contributor Agreement or contributed to any other project under the GitHub Plone organization, including Volto. +- {doc}`plone:contributing/volto` is for people who want to contribute to Volto. + + +### Integrators + +An integrator is someone who uses Volto in their client projects. + +- {doc}`plone:install/create-project` is a guide to bootstrap a new Volto project and start hacking. +- {doc}`getting-started/roadmap` is intended for integrators to assess their knowledge and determine what gaps they would like to fill through available resources. + + +### Users + +A user of Volto is someone who edits content in a Plone content management system with Volto as the frontend. + +- {doc}`user-manual/index` provides information about how to manage content in a Plone site. + + +## Table of Contents ```{toctree} :maxdepth: 2 From e3b1b4bfe78d76ba47225d333b4c9cc75278f541 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 28 Feb 2024 06:30:39 -0800 Subject: [PATCH 02/15] Change page title from "Development recipes" to "Development" --- docs/source/recipes/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/source/recipes/index.md b/docs/source/recipes/index.md index 97133ec6dd..636f0ea4d1 100644 --- a/docs/source/recipes/index.md +++ b/docs/source/recipes/index.md @@ -1,13 +1,13 @@ --- myst: html_meta: - "description": "Volto development recipes" - "property=og:description": "Volto development recipes" - "property=og:title": "Development recipes" - "keywords": "Volto, Plone, frontend, React, development, recipes" + "description": "Volto development" + "property=og:description": "Volto development" + "property=og:title": "Development" + "keywords": "Volto, Plone, frontend, React, development" --- -# Development recipes +# Development ```{toctree} :maxdepth: 1 From 2846cea4b33437005e4b74414544781abb055415 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 28 Feb 2024 06:38:51 -0800 Subject: [PATCH 03/15] Refactor `recipes` to `development` --- docs/source/configuration/how-to.md | 2 +- docs/source/configuration/internalproxy.md | 2 +- docs/source/configuration/settings-reference.md | 4 ++-- docs/source/contributing/index.md | 2 +- docs/source/contributing/language-features.md | 2 +- docs/source/{recipes => development}/appextras.md | 0 docs/source/{recipes => development}/color-picker-widget.md | 0 docs/source/{recipes => development}/contextnavigation.md | 0 docs/source/{recipes => development}/creating-project.md | 0 docs/source/{recipes => development}/creating-views.md | 0 .../source/{recipes => development}/customizing-components.md | 0 docs/source/{recipes => development}/customizing-views.md | 0 docs/source/{recipes => development}/environment-variables.md | 0 docs/source/{recipes => development}/express.md | 0 docs/source/{recipes => development}/folder-structure.md | 0 .../source/{recipes => development}/how-to-restrict-blocks.md | 0 docs/source/{recipes => development}/i18n.md | 0 docs/source/{recipes => development}/ie11compat.md | 0 docs/source/{recipes => development}/images.md | 0 docs/source/{recipes => development}/index.md | 0 docs/source/{recipes => development}/lazyload.md | 0 docs/source/{recipes => development}/pluggables.md | 0 docs/source/{recipes => development}/widget.md | 0 docs/source/index.md | 2 +- docs/source/release-notes/index.md | 2 +- packages/scripts/README.md | 2 +- packages/volto/CHANGELOG.md | 2 +- 27 files changed, 10 insertions(+), 10 deletions(-) rename docs/source/{recipes => development}/appextras.md (100%) rename docs/source/{recipes => development}/color-picker-widget.md (100%) rename docs/source/{recipes => development}/contextnavigation.md (100%) rename docs/source/{recipes => development}/creating-project.md (100%) rename docs/source/{recipes => development}/creating-views.md (100%) rename docs/source/{recipes => development}/customizing-components.md (100%) rename docs/source/{recipes => development}/customizing-views.md (100%) rename docs/source/{recipes => development}/environment-variables.md (100%) rename docs/source/{recipes => development}/express.md (100%) rename docs/source/{recipes => development}/folder-structure.md (100%) rename docs/source/{recipes => development}/how-to-restrict-blocks.md (100%) rename docs/source/{recipes => development}/i18n.md (100%) rename docs/source/{recipes => development}/ie11compat.md (100%) rename docs/source/{recipes => development}/images.md (100%) rename docs/source/{recipes => development}/index.md (100%) rename docs/source/{recipes => development}/lazyload.md (100%) rename docs/source/{recipes => development}/pluggables.md (100%) rename docs/source/{recipes => development}/widget.md (100%) diff --git a/docs/source/configuration/how-to.md b/docs/source/configuration/how-to.md index 0958bcc084..5d4eafd897 100644 --- a/docs/source/configuration/how-to.md +++ b/docs/source/configuration/how-to.md @@ -83,7 +83,7 @@ but also the [lookup mechanism](https://github.com/plone/volto/blob/212026a39fd9aa0e1d6c324f967b51a3daa10b01/packages/volto/src/components/manage/Form/Field.jsx#L151) to understand how things work. -See {doc}`../recipes/widget` for more information. +See {doc}`../development/widget` for more information. ## views diff --git a/docs/source/configuration/internalproxy.md b/docs/source/configuration/internalproxy.md index 86bf599143..8f8f492762 100644 --- a/docs/source/configuration/internalproxy.md +++ b/docs/source/configuration/internalproxy.md @@ -68,4 +68,4 @@ This redefines the request path from the internal proxy of the server side Node. ### Advanced usage -See {doc}`../recipes/environment-variables` for recipes for internal proxy usage. +See {doc}`../development/environment-variables` for recipes for internal proxy usage. diff --git a/docs/source/configuration/settings-reference.md b/docs/source/configuration/settings-reference.md index fbf8ab0378..afa7f85e46 100644 --- a/docs/source/configuration/settings-reference.md +++ b/docs/source/configuration/settings-reference.md @@ -107,7 +107,7 @@ initialReducersBlacklist loadables A mapping of loadable libraries that can be injected into components using the `injectLazyLibs` HOC wrapper. See the [Lazy - loading](../recipes/lazyload) page for more details. + loading](../development/lazyload) page for more details. lazyBundles A mapping of bundles to list of lazy library names. Create new bundles (or @@ -514,7 +514,7 @@ in the `config.settings.serverConfig` object. expressMiddleware A list of ExpressJs middleware that can extend the built-in functionality of - Volto's server. See the [Express](../recipes/express) section for more details. + Volto's server. See the [Express](../development/express) section for more details. criticalCssPath A path relative to the project root that points to an optional CSS file. If diff --git a/docs/source/contributing/index.md b/docs/source/contributing/index.md index b9a37388b4..1e914a43a4 100644 --- a/docs/source/contributing/index.md +++ b/docs/source/contributing/index.md @@ -58,7 +58,7 @@ For developing Volto, follow {doc}`developing-core`. ## Translations All text that can be shown in a browser must be translatable. -Please mark all such strings as translatable as defined in the [i18n guide](../recipes/i18n.md). +Please mark all such strings as translatable as defined in the [i18n guide](../development/i18n.md). (contributing-branch-policy-for-translations-label)= diff --git a/docs/source/contributing/language-features.md b/docs/source/contributing/language-features.md index 256faea1e5..2067e4c4d4 100644 --- a/docs/source/contributing/language-features.md +++ b/docs/source/contributing/language-features.md @@ -70,4 +70,4 @@ have to support. However, Volto (or its dependencies) might not be compatible with old browsers anyways, and you might need to provide some other workarounds to make the build work (and the deprecated browser not crash). You can refer to {doc}`this (outdated) -document <../recipes/ie11compat>` in order to get some hints on how to do it. +document <../development/ie11compat>` in order to get some hints on how to do it. diff --git a/docs/source/recipes/appextras.md b/docs/source/development/appextras.md similarity index 100% rename from docs/source/recipes/appextras.md rename to docs/source/development/appextras.md diff --git a/docs/source/recipes/color-picker-widget.md b/docs/source/development/color-picker-widget.md similarity index 100% rename from docs/source/recipes/color-picker-widget.md rename to docs/source/development/color-picker-widget.md diff --git a/docs/source/recipes/contextnavigation.md b/docs/source/development/contextnavigation.md similarity index 100% rename from docs/source/recipes/contextnavigation.md rename to docs/source/development/contextnavigation.md diff --git a/docs/source/recipes/creating-project.md b/docs/source/development/creating-project.md similarity index 100% rename from docs/source/recipes/creating-project.md rename to docs/source/development/creating-project.md diff --git a/docs/source/recipes/creating-views.md b/docs/source/development/creating-views.md similarity index 100% rename from docs/source/recipes/creating-views.md rename to docs/source/development/creating-views.md diff --git a/docs/source/recipes/customizing-components.md b/docs/source/development/customizing-components.md similarity index 100% rename from docs/source/recipes/customizing-components.md rename to docs/source/development/customizing-components.md diff --git a/docs/source/recipes/customizing-views.md b/docs/source/development/customizing-views.md similarity index 100% rename from docs/source/recipes/customizing-views.md rename to docs/source/development/customizing-views.md diff --git a/docs/source/recipes/environment-variables.md b/docs/source/development/environment-variables.md similarity index 100% rename from docs/source/recipes/environment-variables.md rename to docs/source/development/environment-variables.md diff --git a/docs/source/recipes/express.md b/docs/source/development/express.md similarity index 100% rename from docs/source/recipes/express.md rename to docs/source/development/express.md diff --git a/docs/source/recipes/folder-structure.md b/docs/source/development/folder-structure.md similarity index 100% rename from docs/source/recipes/folder-structure.md rename to docs/source/development/folder-structure.md diff --git a/docs/source/recipes/how-to-restrict-blocks.md b/docs/source/development/how-to-restrict-blocks.md similarity index 100% rename from docs/source/recipes/how-to-restrict-blocks.md rename to docs/source/development/how-to-restrict-blocks.md diff --git a/docs/source/recipes/i18n.md b/docs/source/development/i18n.md similarity index 100% rename from docs/source/recipes/i18n.md rename to docs/source/development/i18n.md diff --git a/docs/source/recipes/ie11compat.md b/docs/source/development/ie11compat.md similarity index 100% rename from docs/source/recipes/ie11compat.md rename to docs/source/development/ie11compat.md diff --git a/docs/source/recipes/images.md b/docs/source/development/images.md similarity index 100% rename from docs/source/recipes/images.md rename to docs/source/development/images.md diff --git a/docs/source/recipes/index.md b/docs/source/development/index.md similarity index 100% rename from docs/source/recipes/index.md rename to docs/source/development/index.md diff --git a/docs/source/recipes/lazyload.md b/docs/source/development/lazyload.md similarity index 100% rename from docs/source/recipes/lazyload.md rename to docs/source/development/lazyload.md diff --git a/docs/source/recipes/pluggables.md b/docs/source/development/pluggables.md similarity index 100% rename from docs/source/recipes/pluggables.md rename to docs/source/development/pluggables.md diff --git a/docs/source/recipes/widget.md b/docs/source/development/widget.md similarity index 100% rename from docs/source/recipes/widget.md rename to docs/source/development/widget.md diff --git a/docs/source/index.md b/docs/source/index.md index ce18a26547..83df2ab1dc 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -59,7 +59,7 @@ A user of Volto is someone who edits content in a Plone content management syste getting-started/index configuration/index theming/index -recipes/index +development/index blocks/index addons/index client/index diff --git a/docs/source/release-notes/index.md b/docs/source/release-notes/index.md index b148fe9e5c..b652794204 100644 --- a/docs/source/release-notes/index.md +++ b/docs/source/release-notes/index.md @@ -6368,7 +6368,7 @@ https://6.docs.plone.org/volto/upgrade-guide/index.html - Added item type as a tooltip in contents @nzambello - Added Italian translations and translated array, token and select widget. @giuliaghisini - Added uploading image preview in FileWidget @iFlameing -- Allow custom express middleware declared with `settings.expressMiddleware`. See [Custom Express middleware](https://6.docs.plone.org/volto/recipes/express.html) @tiberiuichim +- Allow custom express middleware declared with `settings.expressMiddleware`. See [Custom Express middleware](https://6.docs.plone.org/volto/development/express.html) @tiberiuichim ### Bugfix diff --git a/packages/scripts/README.md b/packages/scripts/README.md index 3c85d2d2c1..7f5d96f47a 100644 --- a/packages/scripts/README.md +++ b/packages/scripts/README.md @@ -6,7 +6,7 @@ This package is a library of scripts that are useful to automate certain tasks w It scans and detects i18n messages from the code and adds them to the i18n machinery. -See https://6.docs.plone.org/volto/recipes/i18n.html for more information. +See https://6.docs.plone.org/volto/development/i18n.html for more information. This script is installed in the `node_modules/.bin` directory and can be called via `yarn i18n` or directly in the `scripts` `package.json` part. diff --git a/packages/volto/CHANGELOG.md b/packages/volto/CHANGELOG.md index b148fe9e5c..b652794204 100644 --- a/packages/volto/CHANGELOG.md +++ b/packages/volto/CHANGELOG.md @@ -6368,7 +6368,7 @@ https://6.docs.plone.org/volto/upgrade-guide/index.html - Added item type as a tooltip in contents @nzambello - Added Italian translations and translated array, token and select widget. @giuliaghisini - Added uploading image preview in FileWidget @iFlameing -- Allow custom express middleware declared with `settings.expressMiddleware`. See [Custom Express middleware](https://6.docs.plone.org/volto/recipes/express.html) @tiberiuichim +- Allow custom express middleware declared with `settings.expressMiddleware`. See [Custom Express middleware](https://6.docs.plone.org/volto/development/express.html) @tiberiuichim ### Bugfix From df986f3c7cf2b232754b683fcfdb157c401e5306 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 28 Feb 2024 06:40:30 -0800 Subject: [PATCH 04/15] Refactor `recipes` to `development` --- packages/volto/news/5730.documentation | 1 + 1 file changed, 1 insertion(+) create mode 100644 packages/volto/news/5730.documentation diff --git a/packages/volto/news/5730.documentation b/packages/volto/news/5730.documentation new file mode 100644 index 0000000000..7ac106bda6 --- /dev/null +++ b/packages/volto/news/5730.documentation @@ -0,0 +1 @@ +Improve wayfinding for various Volto audiences. @stevepiercy From ccfaeed0df76dfce8ac595b57d05ea311841e2a3 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 28 Feb 2024 06:49:54 -0800 Subject: [PATCH 05/15] Add change log --- packages/scripts/news/5730.documentation | 1 + 1 file changed, 1 insertion(+) create mode 100644 packages/scripts/news/5730.documentation diff --git a/packages/scripts/news/5730.documentation b/packages/scripts/news/5730.documentation new file mode 100644 index 0000000000..7ac106bda6 --- /dev/null +++ b/packages/scripts/news/5730.documentation @@ -0,0 +1 @@ +Improve wayfinding for various Volto audiences. @stevepiercy From e0c3d1dd3bb3e789d7f447dd030c7b0e53f70432 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 28 Feb 2024 06:54:58 -0800 Subject: [PATCH 06/15] Fix broken link --- docs/source/deploying/performance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/deploying/performance.md b/docs/source/deploying/performance.md index fa0c73bf06..23a8d3bffd 100644 --- a/docs/source/deploying/performance.md +++ b/docs/source/deploying/performance.md @@ -38,7 +38,7 @@ critical-cli https://example.com/ -o critical.css You can pass multiple URLs and screen dimmensions and the extracted CSS will be optimized (duplicate rules will be eliminated, etc). See the [Advanced preset -of cssnano](https://cssnano.co/docs/what-are-optimisations/) for details. One last +of cssnano](https://web.archive.org/web/20230101000000*/https://cssnano.co/docs/what-are-optimisations/) for details. One last optimization applied strips all `@import` declarations from the generated CSS. After that, copy this file to the `public/critical.css` path (configurable From fe7770604ac0d19a8a5d09f944f97ba498d52642 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 28 Feb 2024 07:01:45 -0800 Subject: [PATCH 07/15] Tidy up getting-started/others.md --- docs/source/getting-started/others.md | 68 +++++++++++++++------------ 1 file changed, 37 insertions(+), 31 deletions(-) diff --git a/docs/source/getting-started/others.md b/docs/source/getting-started/others.md index 23ef28370b..1e5b43f3a9 100644 --- a/docs/source/getting-started/others.md +++ b/docs/source/getting-started/others.md @@ -1,26 +1,29 @@ --- myst: html_meta: - "description": "Links to other learning resources." - "property=og:description": "Links to other learning resources." + "description": "Links to learning resources." + "property=og:description": "Links to learning resources." "property=og:title": "learning resources" "keywords": "Volto, Plone, frontend, React, learning resources" --- -# Other learning resources +# Learning resources + +This page lists resources for learning how to use and develop projects in and contribute to Volto. + ## Plone Trainings On the [Plone Training website](https://training.plone.org), you'll find Volto-dedicated training materials, plus other JavaScript-centered trainings. -- [Mastering Plone 6 Development](https://training.plone.org/mastering-plone/) - The comprehensive training on Plone 6 with best practice tips for developers and integrators. -- [Volto Hands-On](https://training.plone.org/voltohandson/index.html) -- [Volto Add-ons Development](https://training.plone.org/voltoaddons/index.html) -- [Effective Volto](https://training.plone.org/effective-volto/index.html) -- [Plone Deployment](https://training.plone.org/plone-deployment/index.html) -- [Volto](https://2022.training.plone.org/volto/index.html) (archived) -- [JavaScript For Plone Developers](https://2022.training.plone.org/javascript/index.html) (archived) +- [Mastering Plone 6 Development](https://training.plone.org/mastering-plone/) + The comprehensive training on Plone 6 with best practice tips for developers and integrators. +- [Volto Hands-On](https://training.plone.org/voltohandson/index.html) +- [Volto Add-ons Development](https://training.plone.org/voltoaddons/index.html) +- [Effective Volto](https://training.plone.org/effective-volto/index.html) +- [Plone Deployment](https://training.plone.org/plone-deployment/index.html) +- [Volto](https://2022.training.plone.org/volto/index.html) (archived) +- [JavaScript For Plone Developers](https://2022.training.plone.org/javascript/index.html) (archived) ## How does it work under the hood @@ -29,19 +32,21 @@ You can watch the talk during the World Plone Day 2021: + ## Presentations at Plone Conferences (PloneConf) and other events -In recent years the React based Volto frontend for Plone has been presented in more and more talks at our yearly Conferences. +In recent years the React based Volto frontend for Plone has been presented in more talks at our yearly conferences. + ### PloneConf 2023 -- [State of Plone Keynote](https://www.youtube.com/watch?v=jl19wuC0wtw&list=PLGN9BI-OAQkSXMXVBXLWQAQr0AF2xM_NU&index=1) -- [Piero Nicolli - Theming Volto in 2024](https://www.youtube.com/watch?v=LkPOsIn1jYY&list=PLGN9BI-OAQkSXMXVBXLWQAQr0AF2xM_NU&index=6) -- [Víctor Fernández de Alba - Breaking boundaries: Plone as headless CMS](https://www.youtube.com/watch?v=43LVtjYyo28&list=PLGN9BI-OAQkSXMXVBXLWQAQr0AF2xM_NU&index=7) -- [Rob Gietema - How to build a site using Nick](https://www.youtube.com/watch?v=ZbdYvNAnamM&list=PLGN9BI-OAQkSXMXVBXLWQAQr0AF2xM_NU&index=18) -- [Alok Kumar - Is your Volto add-on developer friendly?](https://www.youtube.com/watch?v=E6fH3NhR2Hc&list=PLGN9BI-OAQkSXMXVBXLWQAQr0AF2xM_NU&index=20) -- [Dylan Jay and Jefferson Bledsoe - How to implement a Gov Design System in Plone 6](https://www.youtube.com/watch?v=_XmKc7jNIE8&list=PLGN9BI-OAQkSXMXVBXLWQAQr0AF2xM_NU&index=25) -- [Víctor Fernández de Alba - Volto-light-theme: Volto Theming, Reimagined](https://www.youtube.com/watch?v=t2X2NO62J-8) +- [State of Plone Keynote](https://www.youtube.com/watch?v=jl19wuC0wtw&list=PLGN9BI-OAQkSXMXVBXLWQAQr0AF2xM_NU&index=1) +- [Piero Nicolli - Theming Volto in 2024](https://www.youtube.com/watch?v=LkPOsIn1jYY&list=PLGN9BI-OAQkSXMXVBXLWQAQr0AF2xM_NU&index=6) +- [Víctor Fernández de Alba - Breaking boundaries: Plone as headless CMS](https://www.youtube.com/watch?v=43LVtjYyo28&list=PLGN9BI-OAQkSXMXVBXLWQAQr0AF2xM_NU&index=7) +- [Rob Gietema - How to build a site using Nick](https://www.youtube.com/watch?v=ZbdYvNAnamM&list=PLGN9BI-OAQkSXMXVBXLWQAQr0AF2xM_NU&index=18) +- [Alok Kumar - Is your Volto add-on developer friendly?](https://www.youtube.com/watch?v=E6fH3NhR2Hc&list=PLGN9BI-OAQkSXMXVBXLWQAQr0AF2xM_NU&index=20) +- [Dylan Jay and Jefferson Bledsoe - How to implement a Gov Design System in Plone 6](https://www.youtube.com/watch?v=_XmKc7jNIE8&list=PLGN9BI-OAQkSXMXVBXLWQAQr0AF2xM_NU&index=25) +- [Víctor Fernández de Alba - Volto-light-theme: Volto Theming, Reimagined](https://www.youtube.com/watch?v=t2X2NO62J-8) ### PloneConf 2022 @@ -50,27 +55,28 @@ In recent years the React based Volto frontend for Plone has been presented in m Plone 6 site presentations: -- [Rai Way: Plone6 supporting the world of italian information, sports and entertainment](https://www.youtube.com/watch?v=hHHGlSjf5O4&list=PLGN9BI-OAQkQxqQcCZeJefMC8XlA_qv3Z) -- [How Plone Powers Hundreds of Websites at one of the Largest Research Institutions in Europe](https://www.youtube.com/watch?v=bxWt-GEmPcc&list=PLGN9BI-OAQkQxqQcCZeJefMC8XlA_qv3Z) +- [Rai Way: Plone6 supporting the world of italian information, sports and entertainment](https://www.youtube.com/watch?v=hHHGlSjf5O4&list=PLGN9BI-OAQkQxqQcCZeJefMC8XlA_qv3Z) +- [How Plone Powers Hundreds of Websites at one of the Largest Research Institutions in Europe](https://www.youtube.com/watch?v=bxWt-GEmPcc&list=PLGN9BI-OAQkQxqQcCZeJefMC8XlA_qv3Z) Developer/integrator talks: -- [Anatomy of a Volto project](https://www.youtube.com/watch?v=JtNufyFlgc8&list=PLGN9BI-OAQkQxqQcCZeJefMC8XlA_qv3Z) -- [Creating a Volto Theme](https://www.youtube.com/watch?v=AMHN74Jr27Y&list=PLGN9BI-OAQkQxqQcCZeJefMC8XlA_qv3Z) -- [A Deep Dive Into Internals Of Volto](https://www.youtube.com/watch?v=sMeTDRgp3uI&list=PLGN9BI-OAQkQxqQcCZeJefMC8XlA_qv3Z) -- [DevOps Bird's Eye View on the Plone 6 Backend](https://www.youtube.com/watch?v=L5PvGwWC9P4&list=PLGN9BI-OAQkQxqQcCZeJefMC8XlA_qv3Z) +- [Anatomy of a Volto project](https://www.youtube.com/watch?v=JtNufyFlgc8&list=PLGN9BI-OAQkQxqQcCZeJefMC8XlA_qv3Z) +- [Creating a Volto Theme](https://www.youtube.com/watch?v=AMHN74Jr27Y&list=PLGN9BI-OAQkQxqQcCZeJefMC8XlA_qv3Z) +- [A Deep Dive Into Internals Of Volto](https://www.youtube.com/watch?v=sMeTDRgp3uI&list=PLGN9BI-OAQkQxqQcCZeJefMC8XlA_qv3Z) +- [DevOps Bird's Eye View on the Plone 6 Backend](https://www.youtube.com/watch?v=L5PvGwWC9P4&list=PLGN9BI-OAQkQxqQcCZeJefMC8XlA_qv3Z) + ## Previous PloneConfs -- [PloneConf 2021 full Playlist on YouTube](https://www.youtube.com/playlist?list=PLGN9BI-OAQkQDLQinBwdEXpebDTQCwdGi) -- [PloneConf 2020 full Playlist on YouTube](https://www.youtube.com/playlist?list=PLGN9BI-OAQkTJPayNdKIZ8lLDm5RVOLV3) +- [PloneConf 2021 full Playlist on YouTube](https://www.youtube.com/playlist?list=PLGN9BI-OAQkQDLQinBwdEXpebDTQCwdGi) +- [PloneConf 2020 full Playlist on YouTube](https://www.youtube.com/playlist?list=PLGN9BI-OAQkTJPayNdKIZ8lLDm5RVOLV3) ## World Plone Day 2022 World Plone Day is a 24-hour streaming event, with the goal was to promote and educate the public about the benefits of using Plone and of being part of the Plone community. [Full World Plone Day 2022 playlist on Youtube](https://www.youtube.com/playlist?list=PLGN9BI-OAQkQmEqf6O8jeyoFY1b2hD1uL) -- [Plone 6 Volto's Seamless Mode](https://www.youtube.com/watch?v=Mj8pHRBls-w&list=PLGN9BI-OAQkQmEqf6O8jeyoFY1b2hD1uL) -- [Volto add ons separator and carousel](https://www.youtube.com/watch?v=eyTMI5TYcVg&list=PLGN9BI-OAQkQmEqf6O8jeyoFY1b2hD1uL) -- [Weekly Volto Live – Retrospective](https://www.youtube.com/watch?v=WT6OjkSrB20&list=PLGN9BI-OAQkQmEqf6O8jeyoFY1b2hD1uL) -- [Migrating from Classic to Volto](https://www.youtube.com/watch?v=09fg456T90s&list=PLGN9BI-OAQkQmEqf6O8jeyoFY1b2hD1uL) +- [Plone 6 Volto's Seamless Mode](https://www.youtube.com/watch?v=Mj8pHRBls-w&list=PLGN9BI-OAQkQmEqf6O8jeyoFY1b2hD1uL) +- [Volto add ons separator and carousel](https://www.youtube.com/watch?v=eyTMI5TYcVg&list=PLGN9BI-OAQkQmEqf6O8jeyoFY1b2hD1uL) +- [Weekly Volto Live – Retrospective](https://www.youtube.com/watch?v=WT6OjkSrB20&list=PLGN9BI-OAQkQmEqf6O8jeyoFY1b2hD1uL) +- [Migrating from Classic to Volto](https://www.youtube.com/watch?v=09fg456T90s&list=PLGN9BI-OAQkQmEqf6O8jeyoFY1b2hD1uL) From 0f2794ae0a434ec6c23851474f3bff280c207981 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 28 Feb 2024 07:02:21 -0800 Subject: [PATCH 08/15] Fix heading level --- docs/source/getting-started/others.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/getting-started/others.md b/docs/source/getting-started/others.md index 1e5b43f3a9..5eac15479a 100644 --- a/docs/source/getting-started/others.md +++ b/docs/source/getting-started/others.md @@ -66,7 +66,7 @@ Developer/integrator talks: - [DevOps Bird's Eye View on the Plone 6 Backend](https://www.youtube.com/watch?v=L5PvGwWC9P4&list=PLGN9BI-OAQkQxqQcCZeJefMC8XlA_qv3Z) -## Previous PloneConfs +### Previous PloneConfs - [PloneConf 2021 full Playlist on YouTube](https://www.youtube.com/playlist?list=PLGN9BI-OAQkQDLQinBwdEXpebDTQCwdGi) - [PloneConf 2020 full Playlist on YouTube](https://www.youtube.com/playlist?list=PLGN9BI-OAQkTJPayNdKIZ8lLDm5RVOLV3) From 569b809160f72177cbe7a7c38e36b9aac6f960c6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 29 Feb 2024 00:07:31 -0800 Subject: [PATCH 09/15] Rename --- docs/source/getting-started/{roadmap.md => overview.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/source/getting-started/{roadmap.md => overview.md} (100%) diff --git a/docs/source/getting-started/roadmap.md b/docs/source/getting-started/overview.md similarity index 100% rename from docs/source/getting-started/roadmap.md rename to docs/source/getting-started/overview.md From aa0444401393f88f9cf0dfa0cf3e0e4b306db105 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 29 Feb 2024 00:07:53 -0800 Subject: [PATCH 10/15] Move --- docs/source/development/index.md | 7 +++++++ docs/source/{getting-started => development}/overview.md | 0 2 files changed, 7 insertions(+) rename docs/source/{getting-started => development}/overview.md (100%) diff --git a/docs/source/development/index.md b/docs/source/development/index.md index 636f0ea4d1..7360e0b691 100644 --- a/docs/source/development/index.md +++ b/docs/source/development/index.md @@ -9,7 +9,14 @@ myst: # Development +This part of the documentation describes how to develop projects using Volto. + +See {doc}`overview` for a reference of technologies used within the Volto stack, and for suggested topics for further research. + +Or jump in to any topic listed below. + ```{toctree} +:caption: Table of Contents :maxdepth: 1 creating-project diff --git a/docs/source/getting-started/overview.md b/docs/source/development/overview.md similarity index 100% rename from docs/source/getting-started/overview.md rename to docs/source/development/overview.md From 2f46f63a1d39495b352edeaf97705ff6969b00d1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 29 Feb 2024 00:26:20 -0800 Subject: [PATCH 11/15] Update references to overview, formerly roadmap --- docs/source/development/index.md | 3 ++- docs/source/getting-started/index.md | 1 - docs/source/index.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/development/index.md b/docs/source/development/index.md index 7360e0b691..90c28191f8 100644 --- a/docs/source/development/index.md +++ b/docs/source/development/index.md @@ -11,7 +11,7 @@ myst: This part of the documentation describes how to develop projects using Volto. -See {doc}`overview` for a reference of technologies used within the Volto stack, and for suggested topics for further research. +See {doc}`overview` for a reference of technologies used within the Volto stack, and for suggested topics for further learning and research. Or jump in to any topic listed below. @@ -19,6 +19,7 @@ Or jump in to any topic listed below. :caption: Table of Contents :maxdepth: 1 +overview creating-project folder-structure environment-variables diff --git a/docs/source/getting-started/index.md b/docs/source/getting-started/index.md index 15cbdd589a..08a51ba987 100644 --- a/docs/source/getting-started/index.md +++ b/docs/source/getting-started/index.md @@ -12,6 +12,5 @@ myst: ```{toctree} :maxdepth: 1 -roadmap others ``` diff --git a/docs/source/index.md b/docs/source/index.md index 83df2ab1dc..8c577bcbc9 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -41,7 +41,7 @@ A contributor is someone who writes code or documentation for the Volto core pac An integrator is someone who uses Volto in their client projects. - {doc}`plone:install/create-project` is a guide to bootstrap a new Volto project and start hacking. -- {doc}`getting-started/roadmap` is intended for integrators to assess their knowledge and determine what gaps they would like to fill through available resources. +- {doc}`development/overview` is intended for integrators to assess their knowledge and determine what gaps they would like to fill through available resources. ### Users From ef063c7fe6fd57ace42268210022c90ff8a11575 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 29 Feb 2024 00:36:38 -0800 Subject: [PATCH 12/15] Tidy up development overview --- docs/source/development/overview.md | 152 ++++++++++++++-------------- 1 file changed, 75 insertions(+), 77 deletions(-) diff --git a/docs/source/development/overview.md b/docs/source/development/overview.md index 244b11159c..492a8fcc20 100644 --- a/docs/source/development/overview.md +++ b/docs/source/development/overview.md @@ -1,94 +1,92 @@ --- myst: html_meta: - "description": "Volto developer roadmap" - "property=og:description": "Volto developer roadmap" - "property=og:title": "Developer roadmap" - "keywords": "Volto, Plone, frontend, React, developer roadmap, development basic" + "description": "Volto development overview" + "property=og:description": "Volto development overview" + "property=og:title": "Volto development overview" + "keywords": "Volto, Plone, frontend, React, development, overview" --- -# Developer roadmap +# Overview -If you're coming to Volto as a backend Plone developer, you'll have to learn -and adjust to the new frontend-centered development. +If you're coming to Volto as a backend or Classic UI Plone developer, you'll need to learn and adjust to the new frontend-centered development. -But if you already have some frontend development experience any JS frameworks -such as AngularJS, Vue or React, you'll find that Volto is a relatively shallow -framework, structured as a typical {term}`Redux`-centered React application. Although -there will be Volto-specific knowledge to be gained along the way, you can be -productive in a short time. +If you already have some frontend development experience with any JavaScript framework such as AngularJS, Vue, or React, then you'll find that Volto is a relatively shallow framework, structured as a typical {term}`Redux`-centered React application. +Although there will be Volto-specific knowledge to be gained along the way, you can be productive in a short time. -As a reference, here's an overview of knowledge and frameworks, for a more -complete and accurate picture of the Volto framework. +As a reference, here's an overview of knowledge and frameworks, to give a more complete and accurate picture of the Volto framework. -## The foundation -As is the case with similar modern JavaScript-based applications, you should know: +## Foundation + +As is the case with similar modern JavaScript-based applications, you should be familiar the following foundational topics. + +- Modern JavaScript development. + Volto uses next-generation JavaScript. + Follow the [ES6 guide](https://flaviocopes.com/es6/) to get up to speed. +- [Basic React knowledge](https://react.dev/learn/tutorial-tic-tac-toe) to start. + You'll progress along the way. + React itself is a simple and well documented framework. +- A basic understanding of JavaScript. + [CommonJS](https://flaviocopes.com/commonjs/), + [npm packages](https://flaviocopes.com/npm/), + [Yarn](https://flaviocopes.com/yarn/), + [Babel](https://flaviocopes.com/babel/), and + [Webpack](https://flaviocopes.com/webpack/). -- Modern JavaScript development. Volto uses next-generation JavaScript. Follow - the [ES6 guide](https://flaviocopes.com/es6/) to get up to speed. -- React knowledge - [basic level is - fine](https://react.dev/learn/tutorial-tic-tac-toe) for the beginning, you'll progress - along the way. React itself is a simple and well documented framework. -- A basic understanding of JavaScript - [CommonJS](https://flaviocopes.com/commonjs/), - [npm packages](https://flaviocopes.com/npm/), - [Yarn](https://flaviocopes.com/yarn/), - [Babel](https://flaviocopes.com/babel/) and - [Webpack](https://flaviocopes.com/webpack/). ## Basic Volto development -Once you've bootstrapped your Volto project you can already start hacking. Some -of the things you can do at this stage: - -- Configure your text editor for JavaScript and Volto development -- Volto project-based development -- Understand and debug React errors -- Understand React component lifecycle -- Customize (shadow) Volto's builtin components -- Write a new block -- Adjust Volto's builtin settings -- Extend the Pastanaga theme -- Extend the richtext editor capabilities with new buttons and styles -- Use the Redux store -- Deploy your first project - -After you've mastered the foundation and basic Volto development, the -learning-curve smoothes out. Volto uses simple and familiar concepts, -there is nothing on the level of ZCA that needs to be internalized before you -can be really productive. - -## Normal, everyday Volto development - -- Write new Redux actions and reducers -- Create new views for Plone content. -- Install and integrate new JavaScript libraries or third-party React - components -- Create a new Volto addon -- Integrate addon LESS with Volto's theme variables -- Use schema-based forms to write block components -- Write new form widgets -- Write tests for jest -- Write integration tests for Cypress -- Split your code and lazy-load libraries, to improve performance -- Use more advanced React concepts: hooks, context providers, etc. -- Make your code reusable, separate business logic and repeated behaviors as - Higher Order Components (HOCs) -- Write extensible blocks - -## Advanced - -Not really advanced but perhaps less common, here's some stuff you can do: - -- Provide backend-based integration to your Volto code, write `plone.restapi` - endpoints, adapters and other extensions -- Custom integration for blocks to the backend using the block transformers - concept -- Write Express middleware for Volto's server -- Customize Volto's Webpack configuration or project loader using Razzle -- Write a Redux middleware -- Start hacking on Volto. +Once you've {doc}`bootstrapped your Volto project `, you can immediately start hacking. +The following is a list of some the things you can do at this stage. + +- Configure your text editor for JavaScript and Volto development +- Volto project-based development +- Understand and debug React errors +- Understand the React component lifecycle +- Customize (shadow) Volto's built-in components +- Write a new {doc}`block <../blocks/index>` +- Adjust Volto's {doc}`built-in settings <../configuration/index>` +- Extend the Pastanaga {doc}`theme <../theming/index>` +- Extend the {doc}`richtext editor capabilities <../configuration/volto-slate/index>` with new buttons and styles +- Use the Redux store +- {doc}`Deploy <../deploying/index>` your first project + +After you've mastered the foundation and basic Volto development, the learning curve smoothes out. +Volto uses simple and familiar concepts. +There is nothing on the complexity level of ZCA that you would need to internalize before you can be really productive. + + +## Routine Volto development + +While developing a project using Volto, you might perform the following routine tasks. + +- Write new Redux actions and reducers +- Create new views for Plone content +- Install and integrate new JavaScript libraries or third-party React components +- Create a new Volto add-on +- Integrate an add-on's LESS statements with Volto's theme variables +- Use schema-based forms to write block components +- Write new form widgets +- Write tests in Jest +- Write integration tests in Cypress +- Split your code and lazy-load libraries to improve performance +- Use more advanced React concepts, including hooks, context providers, and other topics +- Make your code reusable by separating business logic and repeated behaviors as Higher Order Components (HOCs) +- Write extensible blocks + + +## Occasional Volto development + +From time to time, you might perform the following tasks. + +- Provide backend-based integration for your Volto code by writing `plone.restapi` endpoints, adapters, and other extensions +- Custom integration for blocks to the backend using the block transformers concept +- Write Express middleware for Volto's server +- Customize Volto's Webpack configuration or project loader using Razzle +- Write a Redux middleware +- Start hacking on Volto + ## Add-on first approach From db07b331c91c69b9f9fa4aaefb37e41c8fb6664f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 29 Feb 2024 00:47:35 -0800 Subject: [PATCH 13/15] Purge useless getting-started section, update references, reorder primary navigation items --- docs/source/getting-started/index.md | 16 ---------------- docs/source/index.md | 7 ++++--- .../others.md => tutorials/index.md} | 0 3 files changed, 4 insertions(+), 19 deletions(-) delete mode 100644 docs/source/getting-started/index.md rename docs/source/{getting-started/others.md => tutorials/index.md} (100%) diff --git a/docs/source/getting-started/index.md b/docs/source/getting-started/index.md deleted file mode 100644 index 08a51ba987..0000000000 --- a/docs/source/getting-started/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -myst: - html_meta: - "description": "Getting started with Volto" - "property=og:description": "Getting started with Volto" - "property=og:title": "Getting Started Introduction" - "keywords": "Volto, Plone, frontend, React, Getting, Started" ---- - -# Introduction - -```{toctree} -:maxdepth: 1 - -others -``` diff --git a/docs/source/index.md b/docs/source/index.md index 8c577bcbc9..8e548573d5 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -42,6 +42,7 @@ An integrator is someone who uses Volto in their client projects. - {doc}`plone:install/create-project` is a guide to bootstrap a new Volto project and start hacking. - {doc}`development/overview` is intended for integrators to assess their knowledge and determine what gaps they would like to fill through available resources. +- {doc}`tutorials/index` lists several tutorials and references for further research and learning. ### Users @@ -56,18 +57,18 @@ A user of Volto is someone who edits content in a Plone content management syste ```{toctree} :maxdepth: 2 -getting-started/index +development/index configuration/index theming/index -development/index blocks/index addons/index client/index backend/index deploying/index -upgrade-guide/index user-manual/index +tutorials/index contributing/index +upgrade-guide/index release-notes/index release-management-notes/index ``` diff --git a/docs/source/getting-started/others.md b/docs/source/tutorials/index.md similarity index 100% rename from docs/source/getting-started/others.md rename to docs/source/tutorials/index.md From 5162b5aa5a5b58afeea65fefa7a88a04f0cd500e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 29 Feb 2024 00:56:37 -0800 Subject: [PATCH 14/15] Reorder sections and navigation --- docs/source/index.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/source/index.md b/docs/source/index.md index 8e548573d5..d1cf90184b 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -27,15 +27,6 @@ Thanks to their simplicity and easy access to advanced frontend integration, Vol Choose from the following sections to begin your journey with Volto. -### Contributors - -A contributor is someone who writes code or documentation for the Volto core packages. - -- {doc}`plone:contributing/first-time` is for people who have yet to make a contribution to Plone, Volto, or open source software. -- {doc}`plone:contributing/index` is for people who have not yet signed the Plone Contributor Agreement or contributed to any other project under the GitHub Plone organization, including Volto. -- {doc}`plone:contributing/volto` is for people who want to contribute to Volto. - - ### Integrators An integrator is someone who uses Volto in their client projects. @@ -52,23 +43,32 @@ A user of Volto is someone who edits content in a Plone content management syste - {doc}`user-manual/index` provides information about how to manage content in a Plone site. +### Contributors + +A contributor is someone who writes code or documentation for the Volto core packages. + +- {doc}`plone:contributing/first-time` is for people who have not yet made a contribution to Plone, Volto, or open source software. +- {doc}`plone:contributing/index` is for people who have not yet signed the Plone Contributor Agreement or contributed to any other project under the GitHub Plone organization, including Volto. +- {doc}`plone:contributing/volto` is for people who want to contribute to Volto. + + ## Table of Contents ```{toctree} -:maxdepth: 2 +:maxdepth: 1 development/index configuration/index theming/index blocks/index addons/index -client/index backend/index deploying/index +upgrade-guide/index +client/index user-manual/index tutorials/index contributing/index -upgrade-guide/index release-notes/index release-management-notes/index ``` From ce5da243151845ffd060e11e42798c18c734f456 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 2 Mar 2024 15:44:44 -0800 Subject: [PATCH 15/15] Update phrase --- docs/source/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/index.md b/docs/source/index.md index d1cf90184b..001895aed5 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -29,7 +29,7 @@ Choose from the following sections to begin your journey with Volto. ### Integrators -An integrator is someone who uses Volto in their client projects. +An integrator is someone who uses Volto to build a project. - {doc}`plone:install/create-project` is a guide to bootstrap a new Volto project and start hacking. - {doc}`development/overview` is intended for integrators to assess their knowledge and determine what gaps they would like to fill through available resources.