feat(docsite): optional site_url and site_label link back to the main site

- site.yaml keys site_url and site_label, validated: http(s) URL with a host
  or a path starting with a single /; a label needs a URL
- docs:build and docs:serve flags --site-url and --site-label override them
  the way --base-url overrides base_url
- every page header, the 404 page included, links back with the explicit
  label, else the URL host, else Home; unset output is unchanged
- docs/console/utilities.md documents the keys and flags

internal/docsite/theme_test.go

@@ -77,6 +77,39 @@ func assertCSPSafe(t *testing.T, name, html string) {
 	}
 }
 
+// TestSiteLink checks the optional link back to the main site on a page
+// and on the 404 page: absent without a site URL, labelled explicitly, by
+// the URL host, or Home.
+func TestSiteLink(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		opts Options
+		want []string
+	}{
+		{"unset", Options{}, nil},
+		{"explicit label", Options{SiteURL: "/", SiteLabel: "acme.example"}, []string{`<a class="site-link" href="/"`, `<span class="site-link-label">acme.example</span>`}},
+		{"host label", Options{SiteURL: "https://acme.example/docs"}, []string{`<a class="site-link" href="https://acme.example/docs"`, `<span class="site-link-label">acme.example</span>`}},
+		{"home label", Options{SiteURL: "/"}, []string{`<a class="site-link" href="/"`, `<span class="site-link-label">Home</span>`}},
+	} {
+		opts := tc.opts
+		opts.Root, opts.Commands, opts.Out = themeTree(t), fixtureCommands, filepath.Join(t.TempDir(), "site")
+		if _, problems, err := Build(opts); err != nil || len(problems) > 0 {
+			t.Fatalf("%s: Build: %v %q", tc.name, err, problemLines(problems))
+		}
+		for _, name := range []string{"index.html", "404.html"} {
+			html := readOut(t, opts.Out, name)
+			if tc.want == nil && strings.Contains(html, "site-link") {
+				t.Errorf("%s: %s has a site link", tc.name, name)
+			}
+			for _, w := range tc.want {
+				if !strings.Contains(html, w) {
+					t.Errorf("%s: %s lacks %s", tc.name, name, w)
+				}
+			}
+		}
+	}
+}
+
 func TestBuildSiteMarkers(t *testing.T) {
 	out := buildTheme(t)
 	index := readOut(t, out, "index.html")