docs: Various clarifications

* docs: Getting Started -> Intro, new Getting Started

Several other smaller improvements and clarifications.

* Replace original Getting Started for now

* Fix title

Started in #263 - will handle new Introduction article another time

Author: mholt

src/docs/markdown/automatic-https.md

@@ -122,6 +122,8 @@ In addition, hostnames qualify for publicly-trusted certificates if they:
 
 ## Local HTTPS
 
+Caddy uses HTTPS automatically for all sites with a host (domain, IP, or hostname) specified, including internal and local hosts. Some hosts are either not public (e.g. `127.0.0.1`, `localhost`) or do not generally qualify for publicly-trusted certificates (e.g. IP addresses -- you can get certificates for them, but only from some CAs). These are still served over HTTPS unless disabled.
+
 To serve non-public sites over HTTPS, Caddy generates its own certificate authority (CA) and uses it to sign certificates. The trust chain consists of a root and intermediate certificate. Leaf certificates are signed by the intermediate. They are stored in [Caddy's data directory](/docs/conventions#data-directory) at `pki/authorities/local`.
 
 Caddy's local CA is powered by [Smallstep libraries](https://smallstep.com/certificates/).

src/docs/markdown/caddyfile/concepts.md

@@ -27,7 +27,7 @@ Key points:
 - An optional [**global options block**](#global-options) can be the very first thing in the file.
 - Otherwise, the first line of the Caddyfile is **always** the [address(es)](#addresses) of the site to serve.
 - All [directives](#directives) and [matchers](#matchers) **must** go in a site block. There is no global scope or inheritence across site blocks.
-- If there is **only one site block**, its curly braces `{ }` are optional.
+- If there is only one site block, its curly braces `{ }` are optional.
 
 A Caddyfile consists of at least one or more site blocks, which always starts with one or more [addresses](#addresses) for the site. Any directives appearing before the address will be confusing to the parser.
 
@@ -41,7 +41,7 @@ Opening and closing a **block** is done with curly braces:
 }
 ```
 
-- The open curly brace `{` must be at the end of its line.
+- The open curly brace `{` must be at the end of its line and preceded by a space.
 - The close curly brace `}` must be on its own line.
 
 When there is only one site block, the curly braces (and indentation) are optional. This is for convenience to quickly define a single site, for example, this:
@@ -82,7 +82,7 @@ If a request matches multiple site blocks, the site block with the most specific
 
 ### Directives
 
-[**Directives**](/docs/caddyfile/directives) are keywords which customize how the site is served. For example, a complete file server config might look like this:
+[**Directives**](/docs/caddyfile/directives) are functional keywords which customize how the site is served. They **must** appear within site blocks. For example, a complete file server config might look like this:
 
 ```caddy
 localhost
@@ -102,9 +102,7 @@ In these examples, [`file_server`](/docs/caddyfile/directives/file_server) and [
 
 In the second example, `localhost:9000` is an **argument** because it appears on the same line after the directive.
 
-Note that when the Caddyfile is adapted, directives are sorted according to a specific default [directive order](/docs/caddyfile/directives#directive-order).
-
-**Subdirectives** can appear in directive blocks:
+Sometimes directives can open their own blocks. **Subdirectives** appear on the beginning of each line within directive blocks:
 
 ```caddy
 localhost
@@ -116,6 +114,10 @@ reverse_proxy localhost:9000 localhost:9001 {
 
 Here, `lb_policy` is a subdirective to [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy) (it sets the load balancing policy to use between backends).
 
+**Unless otherwise documented, directives cannot be used within other directive blocks.** For example, `basicauth` cannot be used within `file_server` because the file server does not know how to do authentication; but you can use directives within [`route`](/docs/caddyfile/directives/route), [`handle`](/docs/caddyfile/directives/handle), and [`handle_path`](/docs/caddyfile/directives/handle_path) blocks because they are specifically designed to group directives together.
+
+Note that when the HTTP Caddyfile is adapted, HTTP handler directives are sorted according to a specific default [directive order](/docs/caddyfile/directives#directive-order) unless in a [`route`](/docs/caddyfile/directives/route) block, so the order of appearance of the directives does not matter except in `route` blocks.
+
 
 ### Tokens and quotes
 
@@ -141,17 +143,17 @@ Quotes can be escaped if you need to use quotes in quoted tokens, too:
 directive "\"abc def\""
 ```
 
-Inside quoted tokens, all other characters are treated literally, including spaces, tabs, and newlines. Multi-line tokens are possible:
+To avoid escaping quotes, you can instead use backticks <code>\` \`</code> to enclose tokens; for example:
 
 ```caddy-d
-directive "first line
-	second line"
+directive `{"foo": "bar"}`
 ```
 
-You can also use a backtick <code>`</code> to quote tokens; these are convenient when tokens themselves contain double quotes, e.g. JSON text:
+Inside quoted tokens, all other characters are treated literally, including spaces, tabs, and newlines. Multi-line tokens are thus possible:
 
 ```caddy-d
-directive `{"foo": "bar"}`
+directive "first line
+	second line"
 ```
 
 
@@ -208,9 +210,9 @@ By default, sites bind on all network interfaces. If you wish to override this,
 
 ## Matchers
 
-By default, a directive that injects an HTTP handler applies to all requests (unless otherwise documented).
+HTTP handler directives apply to all requests by default (unless otherwise documented).
 
-Request matchers can be used to classify requests by a given criteria. This concept originates in the [underlying JSON](/docs/json/apps/http/servers/routes/match/) structure, and it's important to know how to use them in the Caddyfile. With matchers, you can specify exactly which requests a certain directive applies to.
+[Request matchers](/docs/caddyfile/matchers) can be used to classify requests by a given criteria. This concept originates in the [underlying JSON](/docs/json/apps/http/servers/routes/match/) structure, and it's important to know how to use them in the Caddyfile. With matchers, you can specify exactly which requests a certain directive applies to.
 
 For directives that support matchers, the first argument after the directive is the **matcher token**. Here are some examples:
 

src/docs/markdown/caddyfile/directives.md

@@ -29,6 +29,8 @@ title: Caddyfile Directives
 
 # Caddyfile Directives
 
+Directives are functional keywords that appear within site [blocks](/docs/caddyfile/concepts#blocks). Sometimes, they may open blocks of their own which can contain _subdirectives_, but directives **cannot** be used within other directives unless noted. For example, you can't use `basicauth` inside a `file_server` block, because `file_server` does not know how to do authentication. However, you _may_ use some directives within special directive blocks like `handle` and `route` because they are specifically designed to group HTTP handler directives.
+
 The following directives come standard with Caddy, and can be used in the HTTP Caddyfile:
 
 <div id="directive-table">

src/docs/markdown/install.md

@@ -33,17 +33,23 @@ Our [official packages](https://github.com/caddyserver/dist) come only with the
 
 ## Static binaries
 
+**If installing onto a production system, we recommend using our official package for your distro if available below.**
+
 1. Obtain a Caddy binary:
-	- [**From releases on GitHub**](https://github.com/caddyserver/caddy/releases) (expand "Assets")
-	- [**From our download page**](/download)
-	- [**By building from source**](/docs/build) (either with `go` or `xcaddy`)
-2. We recommend [installing Caddy as a system service](/docs/running#manual-installation)
+	- [from releases on GitHub](https://github.com/caddyserver/caddy/releases) (expand "Assets")
+	- [from our download page](/download)
+	- [by building from source](/docs/build) (either with `go` or `xcaddy`)
+2. [Install Caddy as a system service.](/docs/running#manual-installation) This is strongly recommended, especially for production servers.
+
+Place the binary in one of your `$PATH` (or `%PATH%` on Windows) directories so you can run `caddy` without typing the full path of the executable file. (Run `echo $PATH` to see the list of directories that qualify.)
+
+You can upgrade static binaries by replacing them with newer versions and restarting Caddy. The [`caddy upgrade` command](/docs/command-line#caddy-upgrade) can make this easy.
+
 
-You can upgrade static binaries by replacing them with newer versions and restarting Caddy.
 
 ## Debian, Ubuntu, Raspbian
 
-Installing this package automatically starts and runs Caddy as a [systemd service](/docs/running#linux-service) named `caddy`. It also comes with a `caddy-api` service which is _not_ enabled by default but should be used if you primarily configure Caddy via its API instead of config files.
+Installing this package automatically starts and runs Caddy as a [systemd service](/docs/running#linux-service) named `caddy`. It also comes with an optional `caddy-api` service which is _not_ enabled by default, but should be used if you primarily configure Caddy via its API instead of config files.
 
 **Stable releases:**
 

src/docs/markdown/running.md

@@ -9,8 +9,8 @@ While Caddy can be run directly with its [command line interface](/docs/command-
 
 - [Linux Service](#linux-service)
   - [Unit Files](#unit-files)
-  - [Using the Service](#using-the-service)
   - [Manual Installation](#manual-installation)
+  - [Using the Service](#using-the-service)
   - [Overrides](#overrides)
 - [Windows Service](#windows-service)
 - [Docker Compose](#docker-compose)
@@ -36,35 +36,6 @@ If you need to switch between the services, you should disable and stop the prev
 <span class="bash">sudo systemctl enable --now caddy-api</span></code></pre>
 
 
-### Using the Service
-
-If using a Caddyfile, you can edit your configuration with `nano`, `vi`, or your preferred editor:
-<pre><code class="cmd bash">sudo nano /etc/caddy/Caddyfile</code></pre>
-
-You can place your static site files in either `/var/www/html` or `/srv`. Make sure the `caddy` user has permission to read the files.
-
-To verify that the service is running:
-<pre><code class="cmd bash">systemctl status caddy</code></pre>
-The status command will also show the location of the currently running service file.
-
-When running with our official service file, Caddy's output will be redirected to `journalctl`. To read your full logs and to avoid lines being truncated:
-<pre><code class="cmd bash">journalctl -u caddy --no-pager | less +G</code></pre>
-
-If using a config file, you can gracefully reload Caddy after making any changes:
-<pre><code class="cmd bash">sudo systemctl reload caddy</code></pre>
-
-You can stop the service with:
-<pre><code class="cmd bash">sudo systemctl stop caddy</code></pre>
-
-<aside class="advice">
-	Do not stop the service to change Caddy's configuration. Stopping the server will incur downtime. Use the reload command instead.
-</aside>
-
-The Caddy process will run as the `caddy` user, which has its `$HOME` set to `/var/lib/caddy`. This means that:
-- The default [data storage location](/docs/conventions#data-directory) (for certificates and other state information) will be in `/var/lib/caddy/.local/share/caddy`.
-- The default [config storage location](/docs/conventions#configuration-directory) (for the auto-saved JSON config, primarily useful for the `caddy-api` service) will be in `/var/lib/caddy/.config/caddy`.
-
-
 ### Manual Installation
 
 Some [installation methods](/docs/install) automatically set up Caddy to run as a service. If you chose a method that did not, you may follow these instructions to do so:
@@ -112,6 +83,37 @@ Verify that it is running:
 Now you're ready to [use the service](#using-the-service)!
 
 
+
+### Using the Service
+
+If using a Caddyfile, you can edit your configuration with `nano`, `vi`, or your preferred editor:
+<pre><code class="cmd bash">sudo nano /etc/caddy/Caddyfile</code></pre>
+
+You can place your static site files in either `/var/www/html` or `/srv`. Make sure the `caddy` user has permission to read the files.
+
+To verify that the service is running:
+<pre><code class="cmd bash">systemctl status caddy</code></pre>
+The status command will also show the location of the currently running service file.
+
+When running with our official service file, Caddy's output will be redirected to `journalctl`. To read your full logs and to avoid lines being truncated:
+<pre><code class="cmd bash">journalctl -u caddy --no-pager | less +G</code></pre>
+
+If using a config file, you can gracefully reload Caddy after making any changes:
+<pre><code class="cmd bash">sudo systemctl reload caddy</code></pre>
+
+You can stop the service with:
+<pre><code class="cmd bash">sudo systemctl stop caddy</code></pre>
+
+<aside class="advice">
+	Do not stop the service to change Caddy's configuration. Stopping the server will incur downtime. Use the reload command instead.
+</aside>
+
+The Caddy process will run as the `caddy` user, which has its `$HOME` set to `/var/lib/caddy`. This means that:
+- The default [data storage location](/docs/conventions#data-directory) (for certificates and other state information) will be in `/var/lib/caddy/.local/share/caddy`.
+- The default [config storage location](/docs/conventions#configuration-directory) (for the auto-saved JSON config, primarily useful for the `caddy-api` service) will be in `/var/lib/caddy/.config/caddy`.
+
+
+
 ### Overrides
 
 The best way to override aspects of the service files is with this command: