Overhaul environment variables documentation

docs/source/configuration/environmentvariables.md

@@ -9,193 +9,186 @@ myst:
 
 # Environment variables
 
-All the environment variables defined at runtime that have the "RAZZLE_" prefix, are available in the browser under window.env
+This page describes environment variables and their usage for configuration of your Volto application at runtime.
 
-ex:
-If we start the application with an env variable
-
-```bash
-RAZZLE_MY_VARIABLE=some_value build/server.js
-```
-
-In the frontend we can access this variable with:
-
-```bash
-window.env.RAZZLE_MY_VARIABLE
-```
 
 ## Runtime environment variables
 
-All the environment variables that are configurable work at runtime, not only at build time. This works since Volto 13 onwards.
-
-````{note}
-Before Volto 13, you'd do:
-
-```bash
-RAZZLE_API_PATH=https://plone.org yarn build && yarn start:prod
+```{versionadded} 13
 ```
 
-From Volto 13 onwards, you can now do:
+All configurable environment variables work at runtime, not only at build time.
+You could, for example, build your Volto application, then start it in production with the `RAZZLE_API_PATH` environment variable.
 
-```bash
+```shell
 yarn build && RAZZLE_API_PATH=https://plone.org yarn start:prod
 ```
-````
 
-This brings you a lot of power since you don't have to rebuild on every config change. You can also generate builds on your CI, then deploy them anywhere.
+This brings you a lot of power since you don't have to rebuild on every configuration change.
+You can also generate builds on your continuous integration, then deploy them anywhere.
 
 
-## Environment variables reference
+## Environment variable reference
 
-### RAZZLE_LEGACY_TRAVERSE
+````{glossary}
+:sorted:
+`RAZZLE_LEGACY_TRAVERSE`
+    If `true`, Volto will construct API URLs without the `/++api++` prefix.
 
-From Volto 14 onwards, Seamless mode is the recommended way of setting up your deployments. However, it forces you to upgrade several packages in the backend (`plone.restapi` and `plone.rest`) and adjust your web server configuration accordingly.
+    This is not needed if you are using {doc}`../deploying/seamless-mode`, which is the recommended way to set up your deployments since Volto 14.
 
-In case you can't afford or change your deployment, you can still upgrade Volto by using the `RAZZLE_LEGACY_TRAVERSE` flag.
+    However, if you are not able to upgrade the packages `plone.restapi` (8.12.1 or greater) and `plone.rest` (2.0.0a1 or greater) in the backend, you can adjust your web server configuration and use the `RAZZLE_LEGACY_TRAVERSE` flag.
 
-```bash
-RAZZLE_LEGACY_TRAVERSE=true yarn start:prod
-```
+    ```shell
+    RAZZLE_LEGACY_TRAVERSE=true yarn start:prod
+    ```
 
-### VOLTO_ROBOTSTXT
+`VOLTO_ROBOTSTXT`
+    You can override the {file}`robots.txt` file with an environment variable called `VOLTO_ROBOTSTXT`.
+    This is useful when using the same build on multiple websites (for example a test website) to forbid robots from crawling it.
+    The following example is a two-line shell command.
 
-You can override the robots.txt file with an environment variable called
-`VOLTO_ROBOTSTXT`. This is useful when using the same build on multiple
-websites (for example a test website) to forbid robots from crawling it.
+    ```shell
+    VOLTO_ROBOTSTXT="User-agent: *
+    Disallow: /" yarn start
+    ```
 
-```
-$ VOLTO_ROBOTSTXT="User-agent: *
-Disallow: /" yarn start
-```
+    ```{note}
+    If you want to use the `VOLTO_ROBOTSTXT` environment variable, your must delete the file `public/robots.txt` from your project to avoid a conflict.
+    ```
 
-```{note}
-If you want to use the `VOLTO_ROBOTSTXT` environment variable, make sure to
-delete the file `public/robots.txt` from your project.
-```
+`DEBUG`
+    It enables several logging points scattered throughout the Volto code.
+    It uses the `volto:` namespace.
+    You can use it in any number of named scopes, all of which are additive and do not cancel one another, or everywhere.
 
-### DEBUG
+    `shadowing` enables component shadowing errors.
+    It displays the errors of the non-compliant customizations in the server console.
+    It helps you identify problems with a customization that does not work as you expect.
 
-It will enable the log several logging points scattered through the Volto code. It uses the `volto:` namespace.
+    ```shell
+    DEBUG=volto:shadowing yarn start
+    ```
 
-```bash
-DEBUG=volto:i18n yarn start
-```
+    `i18n` enables the log of missing internationalization messages in the console.
 
-or
+    ```shell
+    DEBUG=volto:i18n yarn start
+    ```
 
-```bash
-DEBUG=volto:shadowing yarn start
-```
+    `*` enables logging everywhere it exists in Volto.
 
-also
+    ```shell
+    DEBUG=volto:* yarn start
+    ```
 
-```bash
-DEBUG=volto:* yarn start
-```
+`DEBUG_ADDONS_LOADER`
+    Set `DEBUG_ADDONS_LOADER=true` to have Volto generate a file, {file}`addon-dependency-graph.dot`, which contains a graph of all the loaded add-ons.
+    You can use [Graphviz](https://graphviz.org/) to convert this file to an image with:
 
-#### `DEBUG_ADDONS_LOADER`
+    ```
+    dot addon-dependency-graph.dot -Tsvg -o out.svg
+    ```
 
-Set `DEBUG_ADDONS_LOADER=true` to have Volto generate a file, `addon-dependency-graph.dot` which contains a graph of all the loaded addons. You can use [Graphviz](https://graphviz.org/) to convert this file to an image with:
+`ADDONS`
+    You can use the `ADDONS` environment variable to enable and configure add-ons in your project.
 
-```
-dot addon-dependency-graph.dot -Tsvg -o out.svg
-```
+    When running your app, the add-ons will be loaded in the following order:
 
-#### Component shadowing errors (shadowing)
+    -   the file `package.json`
+    -   programmatically set in the file `volto.config.js`
+    -   the environment variable `ADDONS`
 
-It displays the errors of the non-compliant customizations (in server console) if you are experiencing problems with a customization not working.
+    In the environment variable `ADDONS`, you can specify:
 
-#### Internationalization errors (i18n)
+    -   released (or published) packages that were installed previously in your environment and are already present in the `node_modules` directory,
+    -   or add-ons located in the `packages` folder of your project, such as Volto's testing packages.
 
-It will enable the log of missing i18n messages (in console).
+    `ADDONS` can be used to temporarily add an add-on to your build for testing purposes.
 
-## Use add-ons via the `ADDONS` environment variable
+    ```shell
+    yarn add volto-slate
+    ADDONS=volto-slate:asDefault yarn start
+    ```
 
-You can use the `ADDONS` environment variable to enable and configure add-ons in your project.
+    `ADDONS` can also be used to temporarily enable a feature or a set of customizations.
 
-When running your app, the add-ons will be loaded in the following order:
+    ```shell
+    # given a folder './packages/coresandbox', like in vanilla Volto
+    ADDONS=coresandbox:multilingualFixture yarn start
+    ```
 
-- the file `package.json`
-- programmatically set in the file `volto.config.js`
-- the environment variable `ADDONS`
+    If you need to specify several add-ons, separate them with a semicolon (`;`):
 
-In the environment variable `ADDONS`, you can specify:
+    ```shell
+    ADDONS="test-addon;test-addon2" yarn start
+    ```
 
-- released (or published) packages that were installed previously in your environment and are already present in the `node_modules` directory,
-- or addons located in the `packages` folder of your project, such as Volto's testing packages.
+
+    You can specify profiles for installation:
+
+    ```shell
+    ADDONS="test-addon:profile1;test-addon2:profile2" yarn start
+    ```
 
-`ADDONS` can be used to temporarily add an add-on to your build for testing purposes.
+    The following code snippets demonstrate how to configure add-ons.
 
-```bash
-yarn add volto-slate
-ADDONS=volto-slate:asDefault yarn start
-```
+    First in `package.json`:
+
+    ```json
+    "addons": [
+        "@kitconcept/volto-blocks-grid"
+    ]
+    ```
 
-`ADDONS` can also be used to temporarily enable a feature or a set of customizations.
+    Then in `volto.config.js`:
 
-```bash
-# given a folder './packages/coresandbox', like in vanilla Volto
-ADDONS=coresandbox:multilingualFixture yarn start
-```
+    ```js
+    module.exports = {
+        addons: ['@eeacms/volto-accordion-block']
+    }
+    ```
 
-You can specify multiple add-ons, seperated by commas:
+    And finally using `ADDONS`:
 
-```bash
-ADDONS=test-addon,test-addon2 yarn start
-```
+    ```shell
+    yarn add volto-slate
+    ADDONS=volto-slate:asDefault yarn start
+    ```
 
-You can specify profiles for installation:
+    As a result, your app will load the add-ons in the following order:
 
-```bash
-ADDONS=test-addon:profile1,test-addon2:profile2 yarn start
-```
+    -   `@kitconcept/volto-blocks-grid`
+    -   `@eeacms/volto-accordion-block`
+    -   `volto-slate`
 
-The following code snippets demonstrate how to configure add-ons.
-First in `package.json`:
+    ```{important}
+    The `ADDONS` key is a Volto specific configuration.
+    Simply setting `ADDONS` doesn't download the JavaScript package.
+    This has to be covered another way, by either installing the add-on package (with `yarn add`), or loading it as a development package with `mrs-developer`.
+    ```
 
-```json
-"addons": [
-    "@kitconcept/volto-blocks-grid"
-]
-```
-
-...next in `volto.config.js`:
-
-```js
-module.exports = {
-    addons: ['@eeacms/volto-accordion-block']
-}
-```
+`BUILD_DIR`
+    This is a runtime-only environment variable that directs the build to run Volto from a specific location, other than the default folder `build`.
 
-...and finally using `ADDONS`:
-
-```bash
-yarn add volto-slate
-ADDONS=volto-slate:asDefault yarn start
-```
-
-If you need to specify several add-ons, separate them with a semicolon (`;`):
+    ```shell
+    yarn
+    BUILD_DIR=dist node dist/server.js
+    ```
+````
 
-```bash
-yarn add volto-slate
-ADDONS="volto-slate:asDefault;@kitconcept/volto-blocks-grid" yarn start
-```
 
-As a result, your app will load the add-ons in the following order:
+## Access environment variables in a browser
 
-- `@kitconcept/volto-blocks-grid`
-- `@eeacms/volto-accordion-block`
-- `volto-slate`
+All environment variables defined at runtime with the "RAZZLE_" prefix are available in your browser under the `window.env` global object.
+For example, start the application with an environment variable as shown.
 
-```{important}
-The `ADDONS` key is a Volto specific configuration. Simply setting `ADDONS` doesn't download the JavaScript package. This has to be covered by another way, either installing the addon package (with yarn add) or loading it as a development package with mrs-developer.
+```shell
+RAZZLE_MY_VARIABLE=some_value build/server.js
 ```
 
-## BUILD_DIR
+In the frontend, you can access this variable in your code with the following.
 
-This is a runtime-only environment variable that directs the build to run Volto from an especific location, other than the default folder `build`.
-
-```bash
-yarn
-BUILD_DIR=dist node dist/server.js
+```shell
+window.env.RAZZLE_MY_VARIABLE
 ```

packages/volto/news/4581.documentation

@@ -0,0 +1 @@
+Overhaul environment variables documentation. @stevepiercy