Improve wayfinding for various Volto audiences (#5809)

plone · Mar 4, 2024 · 8e08d5a · 8e08d5a
1 parent 4f78851
commit 8e08d5a
Show file tree

Hide file tree

Showing 36 changed files with 275 additions and 246 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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/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

diff --git a/docs/source/recipes/appextras.md → docs/source/development/appextras.md b/docs/source/recipes/appextras.md → docs/source/development/appextras.md
diff --git a/docs/source/recipes/color-picker-widget.md → ...source/development/color-picker-widget.md b/docs/source/recipes/color-picker-widget.md → ...source/development/color-picker-widget.md
diff --git a/docs/source/recipes/contextnavigation.md → docs/source/development/contextnavigation.md b/docs/source/recipes/contextnavigation.md → docs/source/development/contextnavigation.md
diff --git a/docs/source/recipes/creating-project.md → docs/source/development/creating-project.md b/docs/source/recipes/creating-project.md → docs/source/development/creating-project.md
diff --git a/docs/source/recipes/creating-views.md → docs/source/development/creating-views.md b/docs/source/recipes/creating-views.md → docs/source/development/creating-views.md
diff --git a/.../source/recipes/customizing-components.md → ...rce/development/customizing-components.md b/.../source/recipes/customizing-components.md → ...rce/development/customizing-components.md
diff --git a/docs/source/recipes/customizing-views.md → docs/source/development/customizing-views.md b/docs/source/recipes/customizing-views.md → docs/source/development/customizing-views.md
diff --git a/docs/source/recipes/environment-variables.md → ...urce/development/environment-variables.md b/docs/source/recipes/environment-variables.md → ...urce/development/environment-variables.md
diff --git a/docs/source/recipes/express.md → docs/source/development/express.md b/docs/source/recipes/express.md → docs/source/development/express.md
diff --git a/docs/source/recipes/folder-structure.md → docs/source/development/folder-structure.md b/docs/source/recipes/folder-structure.md → docs/source/development/folder-structure.md
diff --git a/.../source/recipes/how-to-restrict-blocks.md → ...rce/development/how-to-restrict-blocks.md b/.../source/recipes/how-to-restrict-blocks.md → ...rce/development/how-to-restrict-blocks.md
diff --git a/docs/source/recipes/i18n.md → docs/source/development/i18n.md b/docs/source/recipes/i18n.md → docs/source/development/i18n.md
diff --git a/docs/source/recipes/ie11compat.md → docs/source/development/ie11compat.md b/docs/source/recipes/ie11compat.md → docs/source/development/ie11compat.md
diff --git a/docs/source/recipes/images.md → docs/source/development/images.md b/docs/source/recipes/images.md → docs/source/development/images.md
diff --git a/docs/source/development/index.md b/docs/source/development/index.md
@@ -0,0 +1,40 @@
+---
+myst:
+  html_meta:
+    "description": "Volto development"
+    "property=og:description": "Volto development"
+    "property=og:title": "Development"
+    "keywords": "Volto, Plone, frontend, React, development"
+---
+
+# 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 learning and research.
+
+Or jump in to any topic listed below.
+
+```{toctree}
+:caption: Table of Contents
+:maxdepth: 1
+
+overview
+creating-project
+folder-structure
+environment-variables
+customizing-components
+customizing-views
+creating-views
+images
+i18n
+express
+lazyload
+appextras
+contextnavigation
+pluggables
+widget
+how-to-restrict-blocks
+color-picker-widget
+ie11compat
+```
diff --git a/docs/source/recipes/lazyload.md → docs/source/development/lazyload.md b/docs/source/recipes/lazyload.md → docs/source/development/lazyload.md
diff --git a/docs/source/development/overview.md b/docs/source/development/overview.md
@@ -0,0 +1,102 @@
+---
+myst:
+  html_meta:
+    "description": "Volto development overview"
+    "property=og:description": "Volto development overview"
+    "property=og:title": "Volto development overview"
+    "keywords": "Volto, Plone, frontend, React, development, overview"
+---
+
+# Overview
+
+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.
+
+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, to give a more complete and accurate picture of the Volto framework.
+
+
+## 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/).
+
+
+## Basic Volto development
+
+Once you've {doc}`bootstrapped your Volto project <plone:install/create-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
+
+Developing for Plone's frontend means to add code to a Volto project.
+The frontend files of the project are created in the `frontend` folder.
+The generator also creates a default add-on in the `frontend/src/addons` folder.
+The project is already configured to use this add-on.
+Add your code and customizations to this add-on, and Volto will load them on start up or a restart.
+This add-on is configured as a theme add-on, so you are able to customize the look and feel of your site as well.
+
+```{seealso}
+For more information about how to develop a Volto project as an add-on, see {doc}`training:voltoaddons/index`.
+```
diff --git a/docs/source/recipes/pluggables.md → docs/source/development/pluggables.md b/docs/source/recipes/pluggables.md → docs/source/development/pluggables.md
diff --git a/docs/source/recipes/widget.md → docs/source/development/widget.md b/docs/source/recipes/widget.md → docs/source/development/widget.md
diff --git a/docs/source/getting-started/index.md b/docs/source/getting-started/index.md
diff --git a/docs/source/getting-started/others.md b/docs/source/getting-started/others.md
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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.