docs/{concept,howto,tutorial}: promote About pages

This change moves the content found at - /docs/concept/about-these-guides/ - /docs/howto/about-these-guides/ - /docs/tutorial/about-these-tutorials/ ... up one level, to their respective top-level containers. The original approach was taken to ensure that a user already inside any of these hierarchies (e.g. reading a tutorial) had an obviously clickable way to reach these pages' explanatory content. The top-level container links on the left hand nav now suit this purpose, rendering a separate "About" page redundant. This change necessarily removes the Netlify redirect from the top-level container page to the About page. The top-level container page contains a category index by default, and this index is left intact (instead of removing it with `index_hide:true`) to provide the {ctrl/cmd}-F "search on page" user with an easy route to any specific category sub-page they might wish to reach. The `hide_summary:true` parameter is used on some pages to exclude them from this automatically generated index, but without excluding them from the left hand nav. This shouldn't affect the content on the *excluded* page in any way. Pages are also updated to use the hugo `{{< tag "xyz" >}}` shortcode, as it was introduced after the relevant pages were originally written. Preview-Path: /docs/concept/ Preview-Path: /docs/howto/ Preview-Path: /docs/tutorial/ Preview-Path: /docs/concept/about-these-guides/ Preview-Path: /docs/howto/about-these-guides/ Preview-Path: /docs/tutorial/about-these-tutorials/ Signed-off-by: Jonathan Matthews <[email protected]> Change-Id: I8ecdbc7953ceecfa5aec6b07cf30b1df56704a92 Reviewed-on: https://review.gerrithub.io/c/cue-lang/cuelang.org/+/1172243 TryBot-Result: CUEcueckoo <[email protected]> Reviewed-by: Paul Jolly <[email protected]>
cue-lang · Nov 17, 2023 · 9424e4e · 9424e4e
1 parent 0185c95
commit 9424e4e
Show file tree

Hide file tree

Showing 31 changed files with 252 additions and 290 deletions.
diff --git a/content/docs/concept/_en.md b/content/docs/concept/_en.md
@@ -3,3 +3,17 @@ title: Concept Guides
 weight: 50
 toc_hide: false
 ---
+
+## About these guides
+
+Concept Guides explain the systems and ideas that drive CUE's design.
+
+They explore the foundations and implications of CUE's theoretical basis in
+depth, and provide background information to help the CUE user discover how
+best to take advantage of its unique and powerful features.
+
+Follow the links on the left hand side of this page to
+[Find a guide]({{< relref "find-a-guide" >}}) and to see a curated list of
+[Popular guides]({{< relref "popular-guides" >}}).
+
+## All available concept guides
diff --git a/content/docs/concept/about-these-guides/en.md b/content/docs/concept/about-these-guides/en.md
diff --git a/content/docs/concept/about-these-guides/page.cue b/content/docs/concept/about-these-guides/page.cue
diff --git a/content/docs/concept/find-a-guide/en.md b/content/docs/concept/find-a-guide/en.md
@@ -2,6 +2,7 @@
 title: Find a guide 🔍
 weight: 20
 toc_hide: false
+hide_summary: true
 ---
 
 # TODO
diff --git a/content/docs/concept/popular-guides/en.md b/content/docs/concept/popular-guides/en.md
@@ -2,6 +2,7 @@
 title: Popular guides
 weight: 30
 toc_hide: false
+hide_summary: true
 ---
 
 # TODO
diff --git a/content/docs/howto/_en.md b/content/docs/howto/_en.md
@@ -3,3 +3,83 @@ title: How-to Guides
 weight: 40
 toc_hide: false
 ---
+
+## About these guides
+
+CUE's documentation site is divided into several sections. The "How-to Guides"
+section contains:
+
+- Guides that demonstrate how to use CUE tools: {{< tag "tooling" >}}
+- Commented CUE guides that briefly illustrate CUE language features and
+  techniques: {{< tag "commented cue" >}}
+- Guides that contain step-by-step instructions for integrating CUE with 3rd
+  party ecosystems and tools: {{< tag "ecosystem" >}}
+- Guides that explain how to encode and decode information stored in languages
+  other than CUE: {{< tag "encodings" >}}
+
+Each guide has one or more tags, displayed at the top and bottom of the page.
+Each tag links to a search page that shows other guides associated with the
+same tag.
+
+## Commented CUE guides
+
+Some How-to Guides use CUE's useful style of
+"[literate](https://en.wikipedia.org/wiki/Literate_programming) configuration".
+We refer to them as {{< tag "commented cue" >}} guides.
+
+Commented CUE guides tend to be short, presenting commented CUE code alongside
+some input data, with a `cue` command showing the concrete result of the
+technique they're demonstrating. Often that result is an error message, showing
+that `cue` has caught the deliberate mistakes in our example data.
+
+Here's an example:
+
+{{{with code "en" "example"}}}
+! exec cue vet .:example data.yml
+cmp stderr out.err
+-- example.cue --
+package example
+
+// CUE comments start with "//".
+// they run to the end of the
+// line
+
+// f1 is a regular field which
+// must be a string
+
+f1: string
+
+// f2 is a required field which
+// must be an integer over 10
+
+f2!: int & >10
+-- data.yml --
+# f1 is actually an integer
+f1: 123
+
+# f2 is actually a string
+f2: "some string value"
+-- out.err --
+f1: conflicting values 123 and string (mismatched types int and string):
+    ./data.yml:2:6
+    ./example.cue:10:5
+f2: conflicting values "some string value" and int (mismatched types string and int):
+    ./data.yml:5:6
+    ./example.cue:15:6
+{{{end}}}
+
+Commented CUE guides require you, the reader, to *modify* their examples
+before you use them. Don't use the CUE exactly as it's presented, but first
+adapt the variable names and data structures to suit your configuration.
+
+Unlike some of our longer, step-by-step guides, the features showcased in
+Commented CUE guides are self-contained and -- we believe! -- easy to adapt to
+any situation. Each guide has a "Related content" section containing links to
+in-depth explanation and discussion of the techniques and language features
+used.
+
+If you find any guides confusing, incomplete, or not detailed enough, then we
+would really appreciate you telling us about your experience - just use the
+"Report an Issue" link at the very bottom of the guide's page!
+
+## All available how-to guides
diff --git a/content/docs/howto/about-these-guides/en.md b/content/docs/howto/about-these-guides/en.md
diff --git a/content/docs/howto/about-these-guides/gen_cache.cue b/content/docs/howto/about-these-guides/gen_cache.cue
diff --git a/content/docs/howto/about-these-guides/page.cue b/content/docs/howto/about-these-guides/page.cue
diff --git a/content/docs/howto/find-a-guide/en.md b/content/docs/howto/find-a-guide/en.md
@@ -2,6 +2,7 @@
 title: Find a guide 🔍
 weight: 20
 toc_hide: false
+hide_summary: true
 ---
 
 # TODO
diff --git a/content/docs/howto/gen_cache.cue b/content/docs/howto/gen_cache.cue
@@ -0,0 +1,16 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				page: {
+					cache: {
+						code: {
+							example: "yqmkRAiwteffdSCxIrFElnHfoKrGbKGeJX1ua55Mpnc="
+						}
+					}
+				}
+			}
+		}
+	}
+}
diff --git a/content/docs/howto/popular-guides/en.md b/content/docs/howto/popular-guides/en.md
@@ -2,6 +2,7 @@
 title: Popular guides
 weight: 30
 toc_hide: false
+hide_summary: true
 ---
 
 # TODO
diff --git a/content/docs/tutorial/_en.md b/content/docs/tutorial/_en.md
@@ -3,3 +3,20 @@ title: Tutorials
 weight: 30
 toc_hide: false
 ---
+
+## About these tutorials
+
+CUE tutorials are practical lessons that help you try out language features,
+workflows, and tools in low risk, practise settings.
+
+To discover the range of tutorials that are available, use the
+[Find a tutorial]({{< relref "find-a-tutorial" >}}) link on the left hand side
+of this page.
+
+If you're new to CUE then start by reading the
+[CUE Tour]({{< relref "/tour" >}}) and
+[Language Guide]({{< relref "/language-guide" >}}), and then try out some
+tutorials specifically selected for you on the
+["New to CUE?"]({{< relref "new-to-cue" >}}) page.
+
+## All available tutorials
diff --git a/content/docs/tutorial/about-these-tutorials/en.md b/content/docs/tutorial/about-these-tutorials/en.md
diff --git a/content/docs/tutorial/about-these-tutorials/page.cue b/content/docs/tutorial/about-these-tutorials/page.cue
diff --git a/content/docs/tutorial/find-a-tutorial/en.md b/content/docs/tutorial/find-a-tutorial/en.md
@@ -2,6 +2,7 @@
 title: Find a tutorial 🔍
 weight:  20
 toc_hide: false
+hide_summary: true
 ---
 
 # TODO
diff --git a/content/docs/tutorial/new-to-cue/en.md b/content/docs/tutorial/new-to-cue/en.md
@@ -2,6 +2,7 @@
 title: New to CUE?
 weight: 30
 toc_hide: false
+hide_summary: true
 ---
 
 # Welcome!

diff --git a/hugo/content/en/docs/concept/_index.md b/hugo/content/en/docs/concept/_index.md
@@ -3,3 +3,17 @@ title: Concept Guides
 weight: 50
 toc_hide: false
 ---
+
+## About these guides
+
+Concept Guides explain the systems and ideas that drive CUE's design.
+
+They explore the foundations and implications of CUE's theoretical basis in
+depth, and provide background information to help the CUE user discover how
+best to take advantage of its unique and powerful features.
+
+Follow the links on the left hand side of this page to
+[Find a guide]({{< relref "find-a-guide" >}}) and to see a curated list of
+[Popular guides]({{< relref "popular-guides" >}}).
+
+## All available concept guides
diff --git a/hugo/content/en/docs/concept/about-these-guides/index.md b/hugo/content/en/docs/concept/about-these-guides/index.md
diff --git a/hugo/content/en/docs/concept/find-a-guide/index.md b/hugo/content/en/docs/concept/find-a-guide/index.md
@@ -2,6 +2,7 @@
 title: Find a guide 🔍
 weight: 20
 toc_hide: false
+hide_summary: true
 ---
 
 # TODO
diff --git a/hugo/content/en/docs/concept/popular-guides/index.md b/hugo/content/en/docs/concept/popular-guides/index.md
@@ -2,6 +2,7 @@
 title: Popular guides
 weight: 30
 toc_hide: false
+hide_summary: true
 ---
 
 # TODO