Merge pull request plone#1413 from plone/install-reorg-1

Port Volto installation docs into the main Plone 6 Installation docs.

Author: stevepiercy

docs/conf.py

@@ -83,6 +83,7 @@
     r"https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors#Identifying_the_issue",
     r"https://github.com/browserslist/browserslist#queries",
     r"https://github.com/nodejs/release#release-schedule",
+    r"https://github.com/nvm-sh/nvm#install--update-script",
     r"https://github.com/plone/cookiecutter-zope-instance#options",
     r"https://github.com/plone/plone.app.contenttypes#migration",
     r"https://github.com/plone/plone.docker#for-basic-usage",
@@ -318,6 +319,7 @@ def source_replace(app, docname, source):
 source_replacements = {
     "{PLONE_BACKEND_MINOR_VERSION}": "6.0",
     "{PLONE_BACKEND_PATCH_VERSION}": "6.0.0.2",
+    "{NVM_VERSION}": "0.39.3",
 }
 
 

docs/glossary.md

@@ -254,8 +254,7 @@ Asynchronous JavaScript and XML
     The server will send a response back to the client, which is then rendered on the client side.
 
 Yeoman
-    A popular scaffolding tool similar to Plone's `mr.bob` or `ZopeSkel`.
-    https://yeoman.io/
+    [Yeoman](https://yeoman.io/) is a popular scaffolding tool similar to Plone's `mr.bob` or `ZopeSkel`.
 
 CommonJS
     A JavaScript package standard, the equivalent of a Python wheel or egg.
@@ -501,6 +500,7 @@ Zope
 
 Make
 make
+GNU make
     [GNU Make](https://www.gnu.org/software/make/) is a tool which controls the generation of executables and other non-source files of a program from the program's source files.
 
     Make gets its knowledge of how to build your program from a file called the _makefile_, which lists each of the non-source files and how to compute it from other files.
@@ -576,4 +576,11 @@ Factory Type Information
     ```{seealso}
     [`FactoryTypeInformation` class source code](https://github.com/zopefoundation/Products.CMFCore/blob/361a30e0c72a15a21f88433b8d5fc49331f36728/src/Products/CMFCore/TypesTool.py#L431)
     ```
+
+`nvm`
+Node Version Manager
+    [`nvm`](https://github.com/nvm-sh/nvm/blob/master/README.md) allows you to quickly install and use different versions of node via the command line.
+
+Node.js
+    [Node.js®](https://nodejs.org/en/) is an open-source, cross-platform JavaScript runtime environment.
 ```

docs/install/install-from-packages.md

@@ -37,33 +37,142 @@ You may host multiple Plone sites on the same server.
 
 ### Pre-requisites for installation
 
--   Python 3.8, 3.9, or 3.10.
--   Cookiecutter
--   Node.JS
--   nvm
--   Yeoman
--   Yarn
--   GNU make
+-   [Python](https://www.python.org/downloads/) 3.8, 3.9, or 3.10.
+-   {term}`Cookiecutter`
+-   {term}`nvm`
+-   {term}`Node.js` LTS 16.x (see "Update" note)
+-   {term}`Yeoman`
+-   {term}`Yarn`
+-   {term}`GNU make`
+
+````{note}
+Update
+:   [Node.js 18 is in LTS state as of 2022-10-25](https://github.com/nodejs/release#release-schedule), and Node.js 16 is now in maintenance mode.
+    However, due to changes in internal SSL libraries, some Volto dependencies have been deprecated and need to be updated in order to continue working in Node.js 18, mainly [Webpack 4](https://github.com/webpack/webpack/issues/14532#issuecomment-947525539).
+    You can still use it, but Node.js should be run under a special flag: `NODE_OPTIONS=--openssl-legacy-provider`.
+
+    ```{seealso}
+    Volto's pull request, [Support Node 18](https://github.com/plone/volto/pull/3699).
+    ```
+````
+
+
+(install-prerequisites-python-label)=
+
+#### Python
 
 Installing Python is beyond the scope of this documentation.
 However, it is recommended to use a Python version manager, [`pyenv`](https://github.com/pyenv/pyenv) that allows you to install multiple versions of Python on your development environment without destroying your system's Python.
 
+
+(install-prerequisites-cookiecutter-label)=
+
+#### Cookiecutter
+
 Install or upgrade {term}`Cookiecutter` in your user's Python:
 
 ```shell
 pip install --user --upgrade cookiecutter
 ```
 
-{ref}`Install nvm and Node.js documentation <frontend-getting-started-install-nvm-label>`.
 
-{ref}`Install Yeoman documentation <frontend-getting-started-yeoman-label>`.
+(install-prerequisites-nvm-label)=
+
+#### nvm
+
+The following terminal session commands use `bash` for the shell.
+Adapt them for your flavor of shell.
+
+```{seealso}
+See the [`nvm` install and update script documentation](https://github.com/nvm-sh/nvm#install--update-script).
+For the `fish` shell, see [`nvm.fish`](https://github.com/jorgebucaran/nvm.fish).
+```
+
+1.  Create your shell profile, if it does not exist.
+
+    ```shell
+    touch ~/.bash_profile
+    ```
+
+2.  Download and run the `nvm` install and update script, and pipe it into `bash`.
+
+    ```shell
+    curl -o- https://raw.githubusercontent.com/creationix/nvm/v{NVM_VERSION}/install.sh | bash
+    ```
+
+3.  Source your profile.
+    Alternatively close the session and open a new one.
+
+    ```shell
+    source ~/.bash_profile
+    ```
+
+4.  Verify that the `nvm` version is that which you just installed or updated:
+
+    ```shell
+    nvm --version
+    ```
+
+
+(install-prerequisites-nodejs-label)=
+
+#### Node.js
 
-{ref}`Install Yarn documentation <frontend-getting-started-yarn-label>`.
+1.  Install or update the supported LTS version of Node.js.
+    This command also activates that version.
+
+    ```shell
+    nvm install 16
+    ```
+
+2.  Verify that the supported version of Node.js is activated.
+
+    ```shell
+    node -v
+    ```
+
+
+(install-prerequisites-yeoman-label)=
+
+#### Yeoman
+
+Install {term}`Yeoman`.
+
+```shell
+npm install -g yo
+```
+
+
+(install-prerequisites-yarn-label)=
+
+#### Yarn
+
+Install the Yarn Classic version (not the latest 2.x one) using `npm`.
+
+1.  Open a terminal and type:
+
+    ```shell
+    npm install yarn@1
+    ```
+
+2.  Verify that Yarn v1.x.x is installed and activated.
+
+    ```shell
+    yarn -v
+    ```
+
+
+(install-prerequisites-make-label)=
+
+#### Make
 
 {term}`Make` comes installed on most Linux distributions.
 On macOS, you must first [install Xcode](https://developer.apple.com/xcode/resources/), then install its command line tools.
 On Windows, it is strongly recommended to [Install Linux on Windows with WSL](https://learn.microsoft.com/en-us/windows/wsl/install), which will include `make`.
 
+Finally, it is a good idea to update your system's version of `make`, because some distributions, especially macOS, have an outdated version.
+Use your favorite search engine or trusted online resource for how to update `make`.
+
 
 (install-packages-install-label)=