go.dev/_content: various formatting fixes

Add a standard 1rem margin above and below key block elements like h1, h2, ..., ol, ul, p.
Today it's very inconsistent and because you get a margin from either the block above
or below, it mostly works out, except in certain cases where text gets jammed together
a bit too much.

Add the auto-TOC generator for use in layouts that define #nav
(nothing yet, but golang.org-migrated pages will).

Add "Table of Contents" to the top of the TOC.

Allow pages to opt out of the TOC by setting HideTOC in their metadata.

Make subtitle heading (Version of Jan 1, 2021) line up horizontally with the TOC.

Preparation for the golang.org -> go.dev move.

Change-Id: Ic9121e5b636155c54e487bcb735ac0bc3f958733
Reviewed-on: https://go-review.googlesource.com/c/website/+/362502
Trust: Russ Cox <rsc@golang.org>
Reviewed-by: Jamal Carvalho <jamal@golang.org>

6 files changed, 35 insertions, 14 deletions

diff --git a/_content/doc/install.html b/_content/doc/install.html
index d238e17f..a0be5594 100644
--- a/_content/doc/install.html
+++ b/_content/doc/install.html
@@ -1,5 +1,6 @@
 <!--{
-    "Title": "Download and install"
+    "Title": "Download and install",
+    "HideTOC": true
 }-->
 <p>
   Download and install Go quickly with the steps described here.
diff --git a/_content/doc/tutorial/getting-started.html b/_content/doc/tutorial/getting-started.html
index 2946f272..6ca9e43c 100644
--- a/_content/doc/tutorial/getting-started.html
+++ b/_content/doc/tutorial/getting-started.html
@@ -127,11 +127,11 @@ go: creating new go.mod: module example/hello
   </li>
 
   <li>
-    In your text editor, create a file hello.go in which to write your code.
+    <p>In your text editor, create a file hello.go in which to write your code.</p>
   </li>
 
   <li>
-    Paste the following code into your hello.go file and save the file.
+    <p>Paste the following code into your hello.go file and save the file.</p>
 
     <pre>
 package main
@@ -170,7 +170,7 @@ func main() {
   </li>
 
   <li>
-    Run your code to see the greeting.
+    <p>Run your code to see the greeting.</p>
 
     <pre>
 $ go run .
diff --git a/_content/site.tmpl b/_content/site.tmpl
index 13cf8d13..f12fad12 100644
--- a/_content/site.tmpl
+++ b/_content/site.tmpl
@@ -99,7 +99,9 @@ window.trackEvent = function(category, action, opt_label, opt_value, opt_noninte
 
 {{/* The Table of Contents is automatically inserted in this <div>.
      Do not delete this <div>. */}}
+{{if not .hidetoc}}
 <div id="nav"></div>
+{{end}}
 
 {{block "layout" .}}{{.Content}}{{end}}
 
diff --git a/go.dev/_content/css/styles.css b/go.dev/_content/css/styles.css
index 28bef832..d4b792c0 100644
--- a/go.dev/_content/css/styles.css
+++ b/go.dev/_content/css/styles.css
@@ -15,6 +15,14 @@ select,
 textarea {
   font: inherit;
 }
+h1, h2, h3, h4, h5, h6, p, ol, ul {
+  margin-top: 1rem;
+  margin-bottom: 1rem;
+}
+table {
+  -webkit-border-horizontal-spacing: 0;
+  -webkit-border-vertical-spacing: 0;
+}
 code,
 pre {
   font-family: SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace;
@@ -454,9 +462,10 @@ a.Footer-link--primary {
 .Dir h1, .Doc h1, .Error h1, .Pkg h1, .Texthtml h1 {
   padding-top: 1rem;
 }
-h2.subtitle {
+h1 + h2.subtitle {
+  margin-top: -1rem;
   font-size: 1.2rem !important;
-  padding-left: 1.5rem;
+  margin-left: 1.25rem; /* note: matches TOC dl */
 }
 .Article-author,
 .Article-date {
@@ -472,16 +481,12 @@ h2.subtitle {
 .Article h5,
 .Article h6 {
   color: #202224;
-  margin: initial;
 }
 .Article h1 {
   font-size: 2.25rem;
-  line-height: 3rem;
 }
 .Article h2 {
   font-size: 1.4rem;
-  line-height: 2rem;
-  margin-top: 1rem;
 }
 .Article h3 {
   font-size: 1.125rem;
@@ -499,9 +504,6 @@ h2.subtitle {
   font-style: normal;
   font-weight: normal;
 }
-.Article p:last-of-type {
-  margin-bottom: 0;
-}
 .Article ol .Article pre {
   background-color: #fafafa;
   border: 0.0625rem solid #dcdee0;
@@ -3902,13 +3904,25 @@ a.error {
   border: 0.0625rem solid #00add8;
 }
 /* Auto-generated table of contents */
+.TOC table {
+  margin-top: 1.25rem;
+  margin-bottom: 1.25rem;
+}
 .TOC table td {
   vertical-align: top;
 }
+.TOC th {
+  padding-left: 1.25rem;
+  max-width: 50rem;
+  text-align: left;
+  font-weight: normal;
+}
 .TOC dl {
-  margin: 1.25rem;
+  margin-left: 1.25rem;
   max-width: 50rem;
   font-size: 0.875rem;
+  margin-block-end: 0;
+  margin-block-start: 0;
 }
 .TOC dd {
   margin: 0 0 0 1.25rem;
diff --git a/go.dev/_content/js/godocs.js b/go.dev/_content/js/godocs.js
index 7984c528..dc744255 100644
--- a/go.dev/_content/js/godocs.js
+++ b/go.dev/_content/js/godocs.js
@@ -83,6 +83,9 @@
 
     var tocTable = $('<table class="unruled"/>').appendTo(nav);
     var tocBody = $('<tbody/>').appendTo(tocTable);
+    var tocHeader = $('<tr/>').appendTo(tocBody);
+    $('<th colspan="2">Table of Contents</th>').appendTo(tocHeader);
+
     var tocRow = $('<tr/>').appendTo(tocBody);
 
     // 1st column
diff --git a/go.dev/_content/site.tmpl b/go.dev/_content/site.tmpl
index 03cd07bc..20a16fa8 100644
--- a/go.dev/_content/site.tmpl
+++ b/go.dev/_content/site.tmpl
@@ -174,6 +174,7 @@
   <script src="/js/misc.js"></script>
   <script src="/js/hats.js"></script>
   <script src="/js/playground.js"></script>
+  <script src="/js/godocs.js"></script>
 </footer>
 </body>
 </html>