docs: Expand install into multiple pages; add example to header docs

src/docs/markdown/build.md

@@ -0,0 +1,66 @@
+---
+title: "Build from source"
+---
+
+# Build from source
+
+Requirements:
+
+- [Go](https://golang.org/dl) 1.14 or newer
+
+Clone the repository:
+
+<pre><code class="cmd bash">git clone "https://github.com/caddyserver/caddy.git"</code></pre>
+
+If you don't have git, you can download the source code as a file archive [from GitHub](https://github.com/caddyserver/caddy). Each [release](https://github.com/caddyserver/caddy/releases) also has source snapshots.
+
+Build:
+
+<pre><code class="cmd"><span class="bash">cd caddy/cmd/caddy/</span>
+<span class="bash">go build</span></code></pre>
+
+<aside class="tip">
+	Due to <a href="https://github.com/golang/go/issues/29228">a bug in Go</a>, these basic steps do not embed version information. If you want the version (<code>caddy version</code>), you need to compile Caddy as a dependency rather than as the main module. Instructions for this are in Caddy's <a href="https://github.com/caddyserver/caddy/blob/master/cmd/caddy/main.go">main.go</a> file. Or, you can use <b>xcaddy</b> which automates this.
+</aside>
+
+## xcaddy
+
+The [`xcaddy` command](https://github.com/caddyserver/xcaddy) is the easiest way to build Caddy with version information and/or plugins.
+
+Requirements:
+
+- Go installed (see above)
+- Make sure [xcaddy](https://github.com/caddyserver/xcaddy/releases) is in your PATH
+
+You do **not** need to download the Caddy source code (it will do that for you).
+
+Then building Caddy (with version information) is as easy as:
+
+<pre><code class="cmd bash">xcaddy build</code></pre>
+
+To build with plugins, use `--with`:
+
+<pre><code class="cmd bash">xcaddy build \
+    --with github.com/caddyserver/nginx-adapter
+	--with github.com/caddyserver/ntlm-transport@v0.1.1</code></pre>
+
+As you can see, you can customize the versions of plugins with `@` syntax. Versions can be a tag name or commit SHA.
+
+Cross-platform compilation with `xcaddy` works the same as with the `go` command (see below).
+
+
+## Cross-platform
+
+Go programs are easy to compile for other platforms. Just set the `GOOS`, `GOARCH`, and/or `GOARM` environment variables that are different. ([See the go documentation for details.](https://golang.org/doc/install/source#environment))
+
+For example, to compile Caddy for Windows when you're not on Windows:
+
+<pre><code class="cmd bash">GOOS=windows go build</code></pre>
+
+Or similarly for Linux ARMv6 when you're not on Linux or on ARMv6:
+
+<pre><code class="cmd bash">GOOS=linux GOARCH=arm GOARM=6 go build</code></pre>
+
+The same works for `xcaddy`. To cross-compile for macOS:
+
+<pre><code class="cmd bash">GOOS=darwin xcaddy build</code></pre>

src/docs/markdown/caddyfile/directives/header.md

@@ -66,3 +66,12 @@ header {
 	Referrer-Policy no-referrer-when-downgrade
 }
 ```
+
+Multiple header directives that are intended to be mutually-exclusive:
+
+```
+route {
+	header           Cache-Control max=age=3600
+	header /static/* Cache-Control max=age=31536000
+}
+```

src/docs/markdown/download.md

@@ -0,0 +1,60 @@
+---
+title: "Download Caddy"
+---
+
+# Download Caddy
+
+All our [official distributions](https://github.com/caddyserver/dist) come with only the standard modules. If you need third-party plugins, [build from source with xcaddy](/docs/build#xcaddy).
+
+
+
+## Static binaries
+
+You can **[download Caddy from GitHub](https://github.com/caddyserver/caddy/releases)**, where new releases are immediately published.
+
+Using `curl`:
+
+<pre><code class="cmd"><span class="bash">curl -OL "https://github.com/caddyserver/caddy/releases/latest/download/ASSET"</span></code></pre>
+
+Using `wget`:
+
+<pre><code class="cmd"><span class="bash">wget "https://github.com/caddyserver/caddy/releases/latest/download/ASSET"</span></code></pre>
+
+
+## Docker
+
+<pre><code class="cmd bash">docker pull caddy</code></pre>
+
+[**View on Docker Hub**](https://hub.docker.com/_/caddy)
+
+
+## Debian, Ubuntu, Raspbian
+
+<pre><code class="cmd"><span class="bash">echo "deb [trusted=yes] https://apt.fury.io/caddy/ /" \
+    | sudo tee -a /etc/apt/sources.list.d/caddy-fury.list</span>
+<span class="bash">sudo apt update</span>
+<span class="bash">sudo apt install caddy</span></code></pre>
+
+Installing this package automatically starts and runs Caddy for you.
+
+
+## Fedora, RedHat, CentOS
+
+Fedora or RHEL/CentOS 8:
+
+<pre><code class="cmd"><span class="bash">dnf install 'dnf-command(copr)'</span>
+<span class="bash">dnf copr enable @caddy/caddy</span>
+<span class="bash">dnf install caddy</span></code></pre>
+
+RHEL/CentOS 7:
+
+<pre><code class="cmd"><span class="bash">yum install yum-plugin-copr</span>
+<span class="bash">yum copr enable @caddy/caddy</span>
+<span class="bash">yum install caddy</span></code></pre>
+
+[**View the Caddy COPR**](https://copr.fedorainfracloud.org/coprs/g/caddy/caddy/)
+
+
+## DigitalOcean
+
+[**Deploy a Caddy droplet on DigitalOcean**](https://marketplace.digitalocean.com/apps/caddy)

src/docs/markdown/getting-started.md

@@ -26,6 +26,8 @@ Welcome to Caddy! This tutorial will explore the basics of using Caddy and help
 
 ---
 
+**If you [installed Caddy](/docs/download) from a package manager, Caddy might already be running as a service. If so, please stop the service before doing this tutorial.**
+
 Let's start by running it:
 
 <pre><code class="cmd bash">caddy</code></pre>
@@ -166,16 +168,16 @@ The Caddyfile seems easier than JSON, but should you always use it? There are pr
 
 JSON | Caddyfile
 -----|----------
-Ubiquitous | Niche
+Full range of Caddy functionality | Most common parts of Caddy functionality
 Easy to generate | Easy to craft by hand
 Easily programmable | Difficult to automate
-Full range of Caddy functionality | Most common parts of Caddy functionality
 Extremely expressive | Moderately expressive
 Allows config traversal | Cannot traverse within Caddyfile
 Partial config changes | Whole config changes only
 Can be exported | Cannot be exported
 Compatible with all API endpoints | Compatible with some API endpoints
 Documentation generated automatically | Documentation is hand-written
+Ubiquitous | Niche
 More efficient | More computational
 Kind of boring | Kind of fun
 **Learn more: [JSON structure](/docs/json/)** | **Learn more: [Caddyfile docs](/docs/caddyfile)**

src/docs/markdown/install.md

@@ -4,46 +4,18 @@ title: "Install"
 
 # Install
 
-Caddy is available for every platform as a [static binary](https://github.com/caddyserver/caddy/releases) (it has no dependencies). You can also [build from source](#build-from-source) to customize your build.
+This page describes how to manually install Caddy as a service.
-
-
-## Official packages
-
-We maintain [official distributions](https://github.com/caddyserver/dist) for the following platforms:
-
-### Docker
-
-<pre><code class="cmd bash">docker pull caddy</code></pre>
-
-[**View on Docker Hub**](https://hub.docker.com/_/caddy)
-
-
-### Debian, Ubuntu, Raspbian
-
-<pre><code class="cmd"><span class="bash">echo "deb [trusted=yes] https://apt.fury.io/caddy/ /" \
-    | sudo tee -a /etc/apt/sources.list.d/caddy-fury.list</span>
-<span class="bash">sudo apt update</span>
-<span class="bash">sudo apt install caddy</span></code></pre>
-
-
-### Fedora, RedHat, CentOS
-
-Read how to [**install the Caddy COPR**](https://copr.fedorainfracloud.org/coprs/g/caddy/caddy/).
-
-
-### DigitalOcean
-
-[**Create a Caddy droplet**](https://marketplace.digitalocean.com/apps/caddy) and get started in 90 seconds.
 
+<aside class="tip">
+	If you <a href="/docs/download">downloaded Caddy</a> using a package manager such as <code>apt</code> or <code>dnf</code>, then Caddy is already installed, and you should jump to <a href="/docs/getting-started">Getting Started</a>.
+</aside>
 
 
 ## Linux service
 
-This section describes how to manually install Caddy as a Linux service.
-
 Requirements:
 
-- `caddy` binary that you downloaded or built from source
+- `caddy` binary that you [downloaded](/docs/download) or [built from source](/docs/build)
 - `systemctl --version` 232 or newer
 - `sudo` privileges
 
@@ -100,27 +72,4 @@ You can stop the service with:
 	Do not stop the service to change Caddy's configuration. Stopping the server will incur downtime. Use the reload command instead.
 </aside>
 
-## Build from source
+Now that Caddy is installed, see our [Getting Started](/docs/getting-started) tutorial to learn how to use it!
-
-Requirements:
-
-- [Go](https://golang.org/dl) 1.14 or newer
-- [Go modules](https://github.com/golang/go/wiki/Modules) enabled
-
-Download the source code:
-
-<pre><code class="cmd bash">git clone "https://github.com/caddyserver/caddy.git"</code></pre>
-
-Build:
-
-<pre><code class="cmd"><span class="bash">cd caddy/cmd/caddy/</span>
-<span class="bash">go build</span></code></pre>
-
-
-### With plugins
-
-Using [xcaddy](https://github.com/caddyserver/xcaddy), you can compile Caddy with extra plugins, for example:
-
-<pre><code class="cmd bash">xcaddy build \
-    --with github.com/caddyserver/nginx-adapter
-	--with github.com/caddyserver/ntlm-transport@v0.1.0</code></pre>

src/includes/docs-nav.html

@@ -1,6 +1,10 @@
 <nav class="sidebar">
 	<ul>
 		<li><a href="/docs/">Welcome</a></li>
+
+		<li class="heading">Get Caddy</li>
+		<li><a href="/docs/download">Download</a></li>
+		<li><a href="/docs/build">Build from source</a></li>
 		<li><a href="/docs/install">Install</a></li>
 		
 		<li class="heading">Tutorials</li>

src/includes/header-nav.html

@@ -2,7 +2,7 @@
 <nav>
 	<input type="search" id="search" placeholder="🔍 Search...">
 	<a href="/v2">v2 <span class="new">new</span></a>
-	<a href="https://github.com/caddyserver/caddy/releases">Download</a>
+	<a href="/docs/download">Download</a>
 	<a href="/docs/">Documentation</a>
 	<a href="https://github.com/caddyserver/caddy">GitHub</a>
 	<a href="https://caddy.community">Community</a>

src/index.html

@@ -24,7 +24,7 @@
 				</h2>
 
 				<div class="download-container">
-					<a href="https://github.com/caddyserver/caddy/releases" class="big blue button">Download</a>
+					<a href="/docs/download" class="big blue button">Download</a>
 					<br>
 					then <a href="/docs/getting-started">learn how to get started</a>
 					<br><br><br>
@@ -74,7 +74,7 @@
 						<!-- <p>
 							A hardened TLS stack powered by the Go standard library serves a significant portion of all Internet traffic.
 						</p> -->
-						<p><a href="https://github.com/caddyserver/caddy/releases" class="blue button">Download</a></p>
+						<p><a href="/docs/download" class="blue button">Download</a></p>
 					</div>
 					<img src="/resources/images/caddy-circle-lock.svg" alt="Caddy is the only server to use HTTPS automatically and by default">
 				</div>
@@ -113,7 +113,7 @@
 						<p>
 							Or use it as a dynamic reverse proxy to any number of backends, complete with active and passive health checks, load balancing, circuit breaking, caching, and more.
 						</p>
-						<p><a href="https://github.com/caddyserver/caddy/releases" class="blue button">Download</a></p>
+						<p><a href="/docs/download" class="blue button">Download</a></p>
 					</div>
 					<img src="/resources/images/proxy-file-server.svg" alt="Caddy is the only server to use HTTPS automatically and by default">
 				</div>
@@ -151,7 +151,7 @@
 
 			<div class="wrapper">
 				<div class="actions text-center">
-					<a href="https://github.com/caddyserver/caddy/releases" class="big blue button">Download</a>
+					<a href="/docs/download" class="big blue button">Download</a>
 					<a href="/docs/command-line" class="big gray button">CLI Docs</a>
 				</div>
 			</div>
@@ -208,7 +208,7 @@
 
 			<div class="wrapper">
 				<div class="actions text-center">
-					<a href="https://github.com/caddyserver/caddy/releases" class="big blue button">Download</a>
+					<a href="/docs/download" class="big blue button">Download</a>
 					<a href="/docs/caddyfile" class="big gray button">Caddyfile Docs</a>
 				</div>
 			</div>
@@ -267,7 +267,7 @@
 						All changes made through the API are persisted to disk so they can continue to be used after restarts.
 					</h2>
 
-					<a href="https://github.com/caddyserver/caddy/releases" class="big blue button">Download</a>
+					<a href="/docs/download" class="big blue button">Download</a>
 					<a href="/docs/api" class="big gray button">API Docs</a>
 					<a href="/docs/getting-started" class="big gray button">Tutorial</a>
 				</div>
@@ -998,7 +998,7 @@
 
 			<div class="wrapper">
 				<div class="text-center">
-					<a href="https://github.com/caddyserver/caddy/releases" class="big blue button">Download</a>
+					<a href="/docs/download" class="big blue button">Download</a>
 					<a href="/docs/" class="big gray button">Documentation</a>
 					<a href="https://caddy.community" class="big gray button">Forum</a>
 				</div>

src/v2.html

@@ -26,7 +26,7 @@
 				<h2>Still the only web server to use <b>TLS automatically and by default.</b> <b>Deploy and scale HTTPS effortlessly</b> with Caddy 2.</h2>
 
 				<div class="action">
-					<a href="https://github.com/caddyserver/caddy/releases" class="big cyan button">Download</a>
+					<a href="/docs/download" class="big cyan button">Download</a>
 					<a href="/docs/getting-started" class="big gray button">Get Started</a>
 					<br>
 					Caddy uses only the Apache 2.0 open source license.
@@ -470,8 +470,8 @@ http://localhost {
 				<br><br>
 
 				<div class="action">
-					<a href="https://github.com/caddyserver/caddy/releases" class="big cyan button">Download</a>
+					<a href="/docs/download" class="big cyan button">Download</a>
-					<a href="/docs" class="big gray button">Documentation</a>
+					<a href="/docs/getting-started" class="big gray button">Get Started</a>
 				</div>
 			</div>
 		</section>