docs: Clarify the 'see the docs' internal links

These are usually not optional and actually explain what a user is interested in. As we don't have documentation partials, duplication isn't in favor of the project maintainer's benefit.

Closes #3927

docs/advanced-usage/backup-recovery.md

@@ -26,8 +26,7 @@ dokku postgres:import [db_name] < [db_name].dump
 
 Dokku doesn't enforce a [300mb](https://devcenter.heroku.com/articles/slug-compiler#slug-size) limit on apps, but it's best practice to keep binary assets outside of git. Since containers are considered volatile in Dokku, external stores like s3 or storage mounts should be used for non-volatile items like user uploads. The Dokku storage core plugin can be used to mount local directories / volumes inside the docker container.
 
-See the [persistent storage documentation](/docs/advanced-usage/persistent-storage.md) for more details.
-
+See the [persistent storage documentation](/docs/advanced-usage/persistent-storage.md) for more information on how to attach persistent storage to your application.
 
 ## Disaster Recovery
 

docs/configuration/domains.md

@@ -115,44 +115,4 @@ dokku domains:report node-js-app --domains-app-enabled
 
 ## Default site
 
-By default, Dokku will route any received request with an unknown HOST header value to the lexicographically first site in the nginx config stack. If this is not the desired behavior, you may want to add the following configuration to the global nginx configuration.
-
-Create the file at `/etc/nginx/conf.d/00-default-vhost.conf`:
-
-```nginx
-server {
-    listen 80 default_server;
-    listen [::]:80 default_server;
-
-    server_name _;
-    access_log off;
-    return 410;
-}
-
-# To handle HTTPS requests, you can uncomment the following section.
-#
-# Please note that in order to let this work as expected, you need a valid
-# SSL certificate for any domains being served. Browsers will show SSL
-# errors in all other cases.
-#
-# Note that the key and certificate files in the below example need to
-# be copied into /etc/nginx/ssl/ folder.
-#
-# server {
-#     listen 443 ssl;
-#     listen [::]:443 ssl;
-#     server_name _;
-#     ssl_certificate /etc/nginx/ssl/cert.crt;
-#     ssl_certificate_key /etc/nginx/ssl/cert.key;
-#     access_log off;
-#     return 410;
-# }
-```
-
-Make sure to reload nginx after creating this file by running `service nginx reload`.
-
-This will catch all unknown HOST header values and return a `410 Gone` response. You can replace the `return 410;` with `return 444;` which will cause nginx to not respond to requests that do not match known domains (connection refused).
-
-The configuration file must be loaded before `/etc/nginx/conf.d/dokku.conf`, so it can not be arranged as a vhost in `/etc/nginx/sites-enabled` that is only processed afterwards.
-
-Alternatively, you may push an app to your Dokku host with a name like "00-default". As long as it lists first in `ls /home/dokku/*/nginx.conf | head`, it will be used as the default nginx vhost.
+This is specific to your proxy plugin of choice. See the [nginx documentation](/docs/configuration/nginx.md#default-site) for more information on how to configure this for the default nginx proxy implementation.

docs/configuration/nginx.md

@@ -225,34 +225,74 @@ By default, Dokku provides custom error pages for the following three categories
 
 These are provided as an alternative to the generic Nginx error page, are shared for _all_ applications, and their contents are located on disk at `/var/lib/dokku/data/nginx-vhosts/dokku-errors`. To customize them for a specific app, create a custom `nginx.conf.sigil` as described above and change the paths to point elsewhere.
 
+## Default site
+
+By default, Dokku will route any received request with an unknown HOST header value to the lexicographically first site in the nginx config stack. If this is not the desired behavior, you may want to add the following configuration to the global nginx configuration.
+
+Create the file at `/etc/nginx/conf.d/00-default-vhost.conf`:
+
+```nginx
+server {
+    listen 80 default_server;
+    listen [::]:80 default_server;
+
+    server_name _;
+    access_log off;
+    return 410;
+}
+
+# To handle HTTPS requests, you can uncomment the following section.
+#
+# Please note that in order to let this work as expected, you need a valid
+# SSL certificate for any domains being served. Browsers will show SSL
+# errors in all other cases.
+#
+# Note that the key and certificate files in the below example need to
+# be copied into /etc/nginx/ssl/ folder.
+#
+# server {
+#     listen 443 ssl;
+#     listen [::]:443 ssl;
+#     server_name _;
+#     ssl_certificate /etc/nginx/ssl/cert.crt;
+#     ssl_certificate_key /etc/nginx/ssl/cert.key;
+#     access_log off;
+#     return 410;
+# }
+```
+
+Make sure to reload nginx after creating this file by running `service nginx reload`.
+
+This will catch all unknown HOST header values and return a `410 Gone` response. You can replace the `return 410;` with `return 444;` which will cause nginx to not respond to requests that do not match known domains (connection refused).
+
+The configuration file must be loaded before `/etc/nginx/conf.d/dokku.conf`, so it can not be arranged as a vhost in `/etc/nginx/sites-enabled` that is only processed afterwards.
+
+Alternatively, you may push an app to your Dokku host with a name like "00-default". As long as it lists first in `ls /home/dokku/*/nginx.conf | head`, it will be used as the default nginx vhost.
+
 ## Domains plugin
 
-See the [domain configuration documentation](/docs/configuration/domains.md).
+See the [domain configuration documentation](/docs/configuration/domains.md) for more information on how to configure domains for your app.
 
 ## Customizing hostnames
 
-See the [customizing hostnames documentation](/docs/configuration/domains.md#customizing-hostnames).
+See the [customizing hostnames documentation](/docs/configuration/domains.md#customizing-hostnames) for more information on how to configure domains for your app.
 
 ## Disabling VHOSTS
 
-See the [disabling vhosts documentation](/docs/configuration/domains.md#disabling-vhosts).
-
-## Default site
-
-See the [default site documentation](/docs/configuration/domains.md#default-site).
+See the [disabling vhosts documentation](/docs/configuration/domains.md#disabling-vhosts) for more information on how to disable domain usage for your app.
 
 ## Running behind a load balancer
 
-See the [load balancer documentation](/docs/configuration/ssl.md#running-behind-a-load-balancer).
+See the [load balancer documentation](/docs/configuration/ssl.md#running-behind-a-load-balancer) for more information on how to configure your nginx config for running behind a network load balancer.
 
 ## SSL Configuration
 
-See the [ssl documentation](/docs/configuration/ssl.md).
+See the [ssl documentation](/docs/configuration/ssl.md) for more information on how to configure SSL certificates for your application.
 
 ## Disabling Nginx
 
-See the [proxy documentation](/docs/advanced-usage/proxy-management.md).
+See the [proxy documentation](/docs/advanced-usage/proxy-management.md) for more information on how to disable nginx as the proxy implementation for your app.
 
 ## Managing Proxy Port mappings
 
-See the [proxy documentation](/docs/advanced-usage/proxy-management.md#proxy-port-mapping).
+See the [proxy documentation](/docs/advanced-usage/proxy-management.md#proxy-port-mapping) for more information on how to manage ports proxied for your app.

docs/configuration/ssl.md

@@ -113,9 +113,9 @@ dokku certs:report node-js-app --ssl-enabled
 
 ## HSTS Header
 
-The [HSTS header](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) is an HTTP header that can inform browsers that all requests to a given site should be made via HTTPS. Dokku does not enables this header by default
+The [HSTS header](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) is an HTTP header that can inform browsers that all requests to a given site should be made via HTTPS. Dokku does enables this header by default for HTTPS requests.
 
-See the [NGINX HSTS documentation](/docs/configuration/nginx.md#hsts-header) for more information.
+See the [NGINX HSTS documentation](/docs/configuration/nginx.md#hsts-header) for more information on how the HSTS configuration can be managed for your application.
 
 ## HTTP/2 support
 

docs/deployment/application-deployment.md

@@ -121,7 +121,7 @@ If you need to redeploy or restart your app:
 dokku ps:rebuild ruby-getting-started
 ```
 
-See the [process scaling documentation](/docs/deployment/process-management.md) for more information.
+See the [process scaling documentation](/docs/deployment/process-management.md) for more information on how to manage your app processes.
 
 ### Deploying with private Git submodules
 
@@ -188,36 +188,36 @@ Prior to every deployment, Dokku will execute a cleanup function. As of 0.5.x, t
 
 ## Adding deploy users
 
-See the [user management documentation](/docs/deployment/user-management.md).
+See the [user management documentation](/docs/deployment/user-management.md) for more information on how to manage users with access to your Dokku server.
 
 ## Default vhost
 
-See the [nginx documentation](/docs/configuration/nginx.md#default-site).
+See the [domains documentation](/docs/configuration/domains.md#default-site) for more information on how to manage the default site.
 
 ## Deploying non-master branch
 
-See the [Git documentation](/docs/deployment/methods/git.md#changing-the-deploy-branch).
+See the [Git documentation](/docs/deployment/methods/git.md#changing-the-deploy-branch) for more information on deploying a non-master branch to your application.
 
 ## Dockerfile deployment
 
-See the [Dockerfile documentation](/docs/deployment/methods/dockerfiles.md).
+See the [Dockerfile documentation](/docs/deployment/methods/dockerfiles.md) for information Dokku's Dockerfile support.
 
 ## Image tagging
 
-See the [image tagging documentation](/docs/deployment/methods/images.md).
+See the [image tagging documentation](/docs/deployment/methods/images.md) for more information on how Docker images can be tagged and deployed for a given application.
 
 ## Specifying a custom buildpack
 
-See the [buildpack documentation](/docs/deployment/methods/buildpacks.md).
+See the [buildpack documentation](/docs/deployment/methods/buildpacks.md) for more information on how to specify a set of custom buildpacks for your application.
 
 ## Removing a deployed app
 
-See the [application management documentation](/docs/deployment/application-management.md#removing-a-deployed-app).
+See the [application management documentation](/docs/deployment/application-management.md#removing-a-deployed-app) for more information on how to remove an application from your Dokku server.
 
 ## Renaming a deployed app
 
-See the [application management documentation](/docs/deployment/application-management.md#renaming-a-deployed-app).
+See the [application management documentation](/docs/deployment/application-management.md#renaming-a-deployed-app) for more information on how an application can be renamed and the impact of doing so upon the application and associated resources.
 
 ## Zero downtime deploy
 
-See the [zero-downtime deploy documentation](/docs/deployment/zero-downtime-deploys.md).
+See the [zero-downtime deploy documentation](/docs/deployment/zero-downtime-deploys.md) for more information on how Dokku enables zero-downtime deploys.

docs/deployment/methods/buildpacks.md

@@ -224,4 +224,4 @@ dokku config:set --global CURL_CONNECT_TIMEOUT=180
 
 ### Clearing buildpack cache
 
-See the [repository management documentation](/docs/advanced-usage/repository-management.md#clearing-app-cache).
+See the [repository management documentation](/docs/advanced-usage/repository-management.md#clearing-app-cache) for more information on how to clear buildpack build cache for an application.

docs/deployment/methods/dockerfiles.md

@@ -116,4 +116,4 @@ in your `Procfile` will be passed as arguments to the `ENTRYPOINT` script instea
 
 ## Exposed ports
 
-See the [port management documentation](/docs/networking/port-management.md).
+See the [port management documentation](/docs/networking/port-management.md) for more information on how Dokku exposes ports for applications and how you can configure these for your app.

docs/deployment/methods/images.md

@@ -22,7 +22,7 @@ The Dokku tags plugin allows you to add Docker image tags to the currently deplo
 
 ### Exposed ports
 
-See the [port management documentation](/docs/networking/port-management.md).
+See the [port management documentation](/docs/networking/port-management.md) for more information on how Dokku exposes ports for applications and how you can configure these for your app.
 
 ### Listing tags for an application
 

docs/networking/proxy-management.md

@@ -84,4 +84,4 @@ dokku proxy:set node-js-app nginx
 
 ### Proxy port mapping
 
-See the [port management documentation](/docs/networking/port-management.md).
+See the [port management documentation](/docs/networking/port-management.md) for more information on how port mappings are managed for an application.