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

cmd/summer/docs_test.go

@@ -72,6 +72,40 @@ func TestDocsBuildRealTree(t *testing.T) {
 	}
 }
 
+// TestDocsBuildSiteFlags checks that --site-url and --site-label reach the
+// header and that an unsafe --site-url is refused.
+func TestDocsBuildSiteFlags(t *testing.T) {
+	out := filepath.Join(t.TempDir(), "site")
+	var buf bytes.Buffer
+	root, err := bonfire.NewRoot("summer", toolCommands(), &buf)
+	if err != nil {
+		t.Fatal(err)
+	}
+	root.SetArgs([]string{"docs:build", "--root", repoRoot, "--out", out, "--site-url", "/", "--site-label", "example.org"})
+	if err := root.Execute(); err != nil {
+		t.Fatalf("docs:build: %v\n%s", err, buf.String())
+	}
+	index, err := os.ReadFile(filepath.Join(out, "index.html"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{`class="site-link" href="/"`, "example.org"} {
+		if !bytes.Contains(index, []byte(want)) {
+			t.Errorf("index.html lacks %s", want)
+		}
+	}
+
+	buf.Reset()
+	root, err = bonfire.NewRoot("summer", toolCommands(), &buf)
+	if err != nil {
+		t.Fatal(err)
+	}
+	root.SetArgs([]string{"docs:build", "--root", repoRoot, "--out", filepath.Join(t.TempDir(), "bad"), "--site-url", "javascript:alert(1)"})
+	if err := root.Execute(); err == nil || !strings.Contains(err.Error(), "--site-url") {
+		t.Fatalf("docs:build --site-url javascript:alert(1): err = %v, want a --site-url error", err)
+	}
+}
+
 // requiredPages lists the guide pages the docs must keep. Each content plan
 // appends the pages it writes.
 var requiredPages = []string{