[docs] Rescue intentional line breaks (ddev#4763) [skip ci]

Author: mattstein

.editorconfig

@@ -12,7 +12,6 @@ indent_style = space
 # embedded yaml in markdown.
 # indent_size = 4
 insert_final_newline = true
-trim_trailing_whitespace = true
 
 # GO files
 [*.go]

docs/content/developers/writing-style-guide.md

@@ -1,6 +1,6 @@
 # Writing Style Guide
 
-This page formalizes the writing conventions we aspire to use in the documentation.
+This page formalizes the writing conventions we aspire to use in the documentation.  
 It’s a living statement of intent and a reference for all contributors.
 
 ## Voice and Tone
@@ -68,7 +68,7 @@ We “run” commands. We don’t “do” them, and the command itself is not a
 
 ### Use Active Third Person
 
-Avoid impersonal language featuring unknown individuals or shadowy organizations.
+Avoid impersonal language featuring unknown individuals or shadowy organizations.  
 “It is recommended,” for example, could be a warmer “we recommend” or “Laravel users recommend”.
 
 Write on behalf of the community and not yourself—use “we” and not “I”.
@@ -149,7 +149,7 @@ DDEV is a product and `ddev` is a binary or console command. DDEV should always
 
 #### Products, Organizations, and Protocols
 
-When in doubt, honor whatever name a product or organization uses in its official materials.
+When in doubt, honor whatever name a product or organization uses in its official materials.  
 Use backticks to differentiate between a product and command, just like DDEV vs. `ddev`.
 
 | Write This 👍 | Not This ❌

docs/content/users/debugging-profiling/step-debugging.md

@@ -11,7 +11,7 @@ All IDEs basically work the same, listening on a port and reacting when they’r
 
 **Key facts:**
 
-* Enable Xdebug by running [`ddev xdebug`](../usage/commands.md#xdebug) or `ddev xdebug on` from your project directory.
+* Enable Xdebug by running [`ddev xdebug`](../usage/commands.md#xdebug) or `ddev xdebug on` from your project directory.  
 It will remain enabled until you start or restart the project.
 * Disable Xdebug for better performance when not debugging with `ddev xdebug off`.
 * `ddev xdebug status` will show Xdebug’s current status.
@@ -57,7 +57,7 @@ When using this zero-configuration option:
 PhpStorm [run/debug configurations](https://www.jetbrains.com/help/phpstorm/creating-and-editing-run-debug-configurations.html) require more setup but may be easier and more flexible for some people.
 
 1. Under the *Run* menu select *Edit configurations*.
-2. Click the *+* in the upper left and choose *PHP Web Application* to create a configuration.
+2. Click the *+* in the upper left and choose *PHP Web Application* to create a configuration.  
 Give it a reasonable name.
 3. Create a “server” for the project. Make sure *Name* is exactly the same as your host (e.g. `my-site.ddev.site`):
     ![PhpStorm server creation](../../images/phpstorm-config-server-config.png)

docs/content/users/install/ddev-installation.md

@@ -115,16 +115,16 @@ Installing and upgrading DDEV are nearly the same thing, because you're upgradin
 
     ### Important Considerations for WSL2 and DDEV
 
-    * WSL2 is supported on Windows 10 and 11.
-    All Windows 10/11 editions, including Windows 10 Home support WSL2.
-    * WSL2 offers a faster, smoother experience.
-    It’s vastly more performant, and you’re less likely to have obscure Windows problems.
-    * Projects should live in the Linux filesystem.
-    WSL2’s Linux filesystem (e.g. `/home/<your_username>`) is much faster, so keep your projects there and **not** in the slower Windows filesystem (`/mnt/c`).
-    * Custom hostnames are managed via the Windows hosts file, not within WSL2.
-    DDEV attempts to manage custom hostnames via the Windows-side hosts file—usually at `C:\Windows\system32\drivers\etc\hosts`—and it can only do this if it’s installed on the Windows side. (DDEV inside WSL2 uses `ddev.exe` on the Windows side as a proxy to update the Windows hosts file.) If `ddev.exe --version` shows the same version as `ddev --version` you’re all set up. Otherwise, install DDEV on Windows using `choco upgrade -y ddev` or by downloading and running the Windows installer. (The WSL2 scripts below install DDEV on the Windows side, taking care of that for you.) If you frequently run into Windows UAC Escalation, you can calm it down by running `gsudo.exe cache on` and `gsudo.exe config CacheMode auto`, see [gsudo docs](https://github.com/gerardog/gsudo#credentials-cache).
-    * WSL2 is not the same as Docker Desktop’s WSL2 engine.
-    Using WSL2 to install and run DDEV is not the same as using Docker Desktop’s WSL2 engine, which itself runs in WSL2, but can serve applications running in both traditional Windows and inside WSL2.
+    * WSL2 is supported on Windows 10 and 11.  
+      All Windows 10/11 editions, including Windows 10 Home support WSL2.
+    * WSL2 offers a faster, smoother experience.  
+      It’s vastly more performant, and you’re less likely to have obscure Windows problems.
+    * Projects should live in the Linux filesystem.  
+      WSL2’s Linux filesystem (e.g. `/home/<your_username>`) is much faster, so keep your projects there and **not** in the slower Windows filesystem (`/mnt/c`).
+    * Custom hostnames are managed via the Windows hosts file, not within WSL2.  
+      DDEV attempts to manage custom hostnames via the Windows-side hosts file—usually at `C:\Windows\system32\drivers\etc\hosts`—and it can only do this if it’s installed on the Windows side. (DDEV inside WSL2 uses `ddev.exe` on the Windows side as a proxy to update the Windows hosts file.) If `ddev.exe --version` shows the same version as `ddev --version` you’re all set up. Otherwise, install DDEV on Windows using `choco upgrade -y ddev` or by downloading and running the Windows installer. (The WSL2 scripts below install DDEV on the Windows side, taking care of that for you.) If you frequently run into Windows UAC Escalation, you can calm it down by running `gsudo.exe cache on` and `gsudo.exe config CacheMode auto`, see [gsudo docs](https://github.com/gerardog/gsudo#credentials-cache).
+    * WSL2 is not the same as Docker Desktop’s WSL2 engine.  
+      Using WSL2 to install and run DDEV is not the same as using Docker Desktop’s WSL2 engine, which itself runs in WSL2, but can serve applications running in both traditional Windows and inside WSL2.
 
     The WSL2 install process involves:
 
@@ -307,31 +307,30 @@ Installing and upgrading DDEV are nearly the same thing, because you're upgradin
 
     ```json
     {
-        "image": "mcr.microsoft.com/devcontainers/universal:2",
-        "features": {
-            "ghcr.io/devcontainers/features/docker-in-docker:1": {},
-            "ghcr.io/ddev/ddev/install-ddev:latest": {}
-        },
-        "portsAttributes": {
+      "image": "mcr.microsoft.com/devcontainers/universal:2",
+      "features": {
+        "ghcr.io/devcontainers/features/docker-in-docker:1": {},
+        "ghcr.io/ddev/ddev/install-ddev:latest": {}
+      },
+      "portsAttributes": {
         "3306": {
-            "label": "database"
+          "label": "database"
         },
         "8027": {
-            "label": "mailhog"
+          "label": "mailhog"
         },
         "8036": {
-            "label": "phpmyadmin"
+          "label": "phpmyadmin"
         },
         "8080": {
-            "label": "web http"
+          "label": "web http"
         },
         "8443": {
-            "label": "web https"
+          "label": "web https"
         }
-        },
-        "postCreateCommand": "bash -c 'ddev config global --omit-containers=ddev-router && ddev config --auto && ddev debug download-images'"
+      },
+      "postCreateCommand": "bash -c 'ddev config global --omit-containers=ddev-router && ddev config --auto && ddev debug download-images'"
     }
-
     ```
 
     !!!note "Normal Linux installation also works"

docs/content/users/install/shell-completion.md

@@ -36,7 +36,7 @@ Shells like bash and zsh need help to do this though, they have to know what the
         curl -sSLf https://github.com/ddev/ddev/releases/download/${VERSION}/ddev_shell_completion_scripts.${VERSION}.tar.gz
         tar -zxf ddev_shell_completion_scripts.${VERSION}.tar.gz
         ```
-    2. Then `sudo mkdir -p /usr/share/bash-completion/completions && sudo cp ddev_bash_completion.sh /usr/share/bash-completion/completions/ddev`. This deploys the `ddev_bash_completion.sh` script where it needs to be. Again, every Linux distro has a different technique, and you may have to figure yours out.
+    2. Run `sudo mkdir -p /usr/share/bash-completion/completions && sudo cp ddev_bash_completion.sh /usr/share/bash-completion/completions/ddev`. This deploys the `ddev_bash_completion.sh` script where it needs to be. Again, every Linux distro has a different technique, and you may have to figure yours out.
 
     If you installed DDEV using `apt install` then the `ddev_bash_completion.sh` file is already available in `/usr/bin/ddev_bash_completion.sh`. Starting with DDEV v1.21.2 this will be automatically installed into `/usr/share/bash-completion/completions`.
 

docs/content/users/topics/hosting.md

@@ -12,7 +12,7 @@ This may be appropriate for small or abandoned sites that have special requireme
 Here’s how to try it for yourself:
 
 1. Install DDEV on an internet-connected Linux server. (You’re responsible for your firewall and maintenance of the server!)
-2. On Debian/Ubuntu, you can set up a simple firewall with
+2. On Debian/Ubuntu, you can set up a simple firewall with  
 `ufw allow 80 && ufw allow 443 && ufw allow 22 && ufw enable`.
 3. Point DNS for the site you’re going to host to the server.
 4. Before proceeding, your system and your project must be accessible on the internet on port 80 and your project DNS name (`myproject.example.com`) must resolve to the appropriate server.
@@ -29,7 +29,7 @@ Here’s how to try it for yourself:
 
     ```
     if ($http_x_forwarded_proto = "http") {
-    return 301 https://$host$request_uri;
+      return 301 https://$host$request_uri;
     }
     ```
 

docs/content/users/usage/architecture.md

@@ -1,6 +1,6 @@
 # How DDEV Works
 
-DDEV is a [Go](https://go.dev) application that stores its configuration in [files on your workstation](#directory-tour).
+DDEV is a [Go](https://go.dev) application that stores its configuration in [files on your workstation](#directory-tour).  
 It uses those blueprints to mount your project files into [Docker containers](#container-architecture) that facilitate the operation of a local development environment.
 
 DDEV writes and uses [docker-compose](https://docs.docker.com/compose/) files for you, which is a detail you can cheerfully ignore unless you’re Docker-curious or [defining your own services](../extend/custom-compose-files.md).
@@ -16,7 +16,7 @@ The [global configuration directory](#global-files) is used to keep track of you
 A project’s `.ddev` directory can be intimidating at first, so let’s take a look at what lives in there.
 
 !!!tip "Yours May Differ Slightly"
-    You may have some directories or files that aren’t listed here, likely added by custom services.
+    You may have some directories or files that aren’t listed here, likely added by custom services.  
     For example, if you see a `solr` directory, it probably pertains to a custom Solr [add-on service](../extend/additional-services.md).
 
 `apache` directory

docs/content/users/usage/cms-settings.md

@@ -14,19 +14,19 @@ While this reduces setup time for new users, makes it easier to try out a CMS, a
 
 There are several ways to back off DDEV’s CMS settings management:
 
-1. **Take control of files by removing the `#ddev-generated` comment.**
+1. **Take control of files by removing the `#ddev-generated` comment.**  
 DDEV will automatically update any it’s added containing a `#ddev-generated` comment. This means you don’t need to touch that file, but also that any changes you make will be overwritten. As soon as you remove the comment, DDEV will ignore that file and leave you fully in control over it. (Don’t forget to check it into version control!)
 
     !!!tip "Reversing the change"
         If you change your mind and want DDEV to take over the file again, delete it and run [`ddev start`](../usage/commands.md#start). DDEV will recreate its own version, which you may want to remove from your Git project.
 
-2. **Disable settings management.**
+2. **Disable settings management.**  
 You can tell DDEV to use a specific project type without creating settings files by either setting [`disable_settings_management`](../configuration/config.md#disable_settings_management) to `true` or running [`ddev config --disable-settings-management`](../configuration/config.md#type).
 
-3. **Switch to the generic PHP project type.**
+3. **Switch to the generic PHP project type.**  
 If you don’t want DDEV’s CMS-specific settings, you can switch your project to the generic `php` type by editing [`type: php`](../configuration/config.md#type) in the project’s settings or running [`ddev config --project-type=php`](../usage/commands.md#config). DDEV will no longer create or tweak any settings files. You’ll lose any perks from the nginx configuration for the CMS, but you can always customize [nginx settings](../extend/customization-extendibility.md#custom-nginx-configuration) or [Apache settings](../extend/customization-extendibility.md#custom-apache-configuration) separately.
 
-4. **Un-set the `$IS_DDEV_PROJECT` environment variable.**
+4. **Un-set the `$IS_DDEV_PROJECT` environment variable.**  
 This environment variable is set `true` by default in DDEV’s environment, and can be used to fence off DDEV-specific behavior. When it’s empty, the important parts of `settings.ddev.php` and `AdditionalSettings.php` (for TYPO3) are not executed. This means that DDEV’s `settings.ddev.php` won’t be invoked if it somehow ends up in a production environment or in a non-DDEV local development environment.
 
 !!!tip "Ignore `.ddev/.gitignore`"
@@ -61,42 +61,42 @@ $settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml'
 
         ```php
         /**
-        * DDEV environments will have $databases (and other settings) set
-        * by an auto-generated file. Make alterations here for this site
-        * in a multisite environment.
-        */
+         * DDEV environments will have $databases (and other settings) set
+         * by an auto-generated file. Make alterations here for this site
+         * in a multisite environment.
+         */
         elseif (getenv('IS_DDEV_PROJECT') == 'true') {
-        /**
-            * Alter database settings and credentials for DDEV environment.
-            * Includes loading the DDEV-generated `default/settings.ddev.php`.
-            */
-        include $app_root . '/' . $site_path . '/settings.databases.ddev.inc';
+          /**
+           * Alter database settings and credentials for DDEV environment.
+           * Includes loading the DDEV-generated `default/settings.ddev.php`.
+           */
+          include $app_root . '/' . $site_path . '/settings.databases.ddev.inc';
         }
         ```
 
     2. Add a `settings.databases.ddev.inc` in each `site/{site_name}/`:
 
         ```php
         /**
-        * Fetch DDEV-generated database credentials and other settings.
-        */
+         * Fetch DDEV-generated database credentials and other settings.
+         */
         require $app_root . '/sites/default/settings.ddev.php';
 
-        /*
-        * Alter default database for this site. `settings.ddev.php` will have
-        * “reset” this to 'db'.
-        */
+        /**
+         * Alter default database for this site. `settings.ddev.php` will have
+         * “reset” this to 'db'.
+         */
         $databases['default']['default']['database'] = 'site_name';
         ```
 
     3. Update your [`web_environment`](../configuration/config.md#web_environment) config option if you’re using site aliases:
 
         ```yaml
         web_environment:
-        # Make DDEV Drush shell PIDs last for entire life of the container
-        # so `ddev drush site:set @alias` persists for all Drush connections.
-        # https://chrisfromredfin.dev/posts/drush-use-ddev/
-        - DRUSH_SHELL_PID=PERMANENT
+          # Make DDEV Drush shell PIDs last for entire life of the container
+          # so `ddev drush site:set @alias` persists for all Drush connections.
+          # https://chrisfromredfin.dev/posts/drush-use-ddev/
+          - DRUSH_SHELL_PID=PERMANENT
         ```
 
 ### TYPO3 Specifics

docs/content/users/usage/database-management.md

@@ -7,7 +7,7 @@ DDEV provides lots of flexibility for managing your databases between your local
 
 ## Database Imports
 
-Import a database with one command, from one of the following file formats:
+Import a database with one command, from one of the following file formats:  
 **.sql, .sql.gz, .mysql, .mysql.gz, .tar, .tar.gz, and .zip**.
 
 Here’s an example of a database import using DDEV:

docs/content/users/usage/developer-tools.md

@@ -58,7 +58,7 @@ Use [`ddev composer`](../usage/commands.md#composer) (Composer inside the contai
 * On some older configurations of Docker Desktop for Windows, symlinks are created in the container as “simulated symlinks”, or XSym files. These special text files behave as symlinks inside the container (on CIFS filesystem), but appear as simple text files on the Windows host. (On the CIFS filesystem used by Docker for Windows, inside the container, there is no capability to create real symlinks even though Windows now has this capability.)
 * DDEV attempts to clean up for this situation. Since Windows 10/11+ (in developer mode) can create real symlinks, DDEV scans your repository after a `ddev composer` command and attempts to convert XSym files into real symlinks. On older versions of Windows 10, it can only do this if your Windows 10 workstation is set to “Developer Mode”.
 * To enable developer mode on Windows 10/11+, search for “developer” in settings:
-    ![Finding developer mode](../../images/developer-mode-1.png)
+    ![Finding developer mode](../../images/developer-mode-1.png)  
     ![Setting developer mode](../../images/developer-mode-2.png)
 
 ## Email Capture and Review (MailHog)

docs/content/users/usage/troubleshooting.md

@@ -174,6 +174,7 @@ If you get a 404 with “No input file specified” (nginx) or a 403 with “For
 If `ddev start` fails, it’s most often because the `web` or `db` container fails to start. In this case, the error message from `ddev start` says something like “Failed to start <project>: db container failed: log=, err=container exited, please use 'ddev logs -s db' to find out why it failed”. You can`ddev logs -s db` to find out what happened.
 
 If you see any variant of “no space left on device” in the logs when using Docker Desktop, it means you have to increase or clean up Docker’s file space. Increase the “Disk image size” setting under “Resources” in Docker’s Preferences:
+
 ![Docker disk space](../../images/docker-disk-image-size.png)
 
 If you see “no space left on device” on Linux, it most likely means your filesystem is full.