docs: present a short CUE example on /docs

This updates the opening of the /docs landing page and includes a very
brief example of some CUE validating some data.

The introductory prose is updated and made shorter, in order to place
some CUE in front of the newcomer immediately - as soon as they reach
the docs section. It uses (arguably) the shortest possible CUE example
that directly and plainly communicates some of CUE's power and elegance
- hopefully prompting the reader to continue clicking through the site.

The leading prose is lifted directly from the the opening of the
/docs/introduction page proposed in https://cuelang.org/cl/1195016:

(a) because it fulfills the site's needs in both locations (summarising
    CUE succinctly, and leading naturally on to the short example), and
(b) because we don't know which page a complete newcomer will land on,
    and this prose encapsulates the information we want such a user to
    internalise quickly, in both locations.

The brevity of the example CUE is important, as we don't want to push
the "How to use this documentation" section below the fold. The prose
selected is optimised to achieve this in low resolution tests (1024x768
was targetted), so that the reader's eye might still be lead on to the
explanatory cards at the end of the page. A sentence drawing the reader
to the cards is added to that section's introduction. To increase the
chances of the section being visible on smaller (desktop) screens, the
per-page mechanism to prevent the minimum-version notification popup
(introduced in https://cuelang.org/cl/1178371) is engaged on the /docs
landing page.

Preview-Path: /docs/
Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: Ie9c20bd8feec9245bff40bc9a544b2f5bf147836
Reviewed-on: https://review.gerrithub.io/c/cue-lang/cuelang.org/+/1197437
TryBot-Result: CUEcueckoo <[email protected]>
Reviewed-by: Paul Jolly <[email protected]>

content/docs/_en.md

@@ -3,30 +3,49 @@ title: "Documentation"
 index_hide: true
 cascade:
   header_type: wide
+disableNotification: true
 ---
 
 # Welcome to CUE!
 
-CUE is an open-source data validation language and inference engine
-with its roots in logic programming.
-Although the language is not a general-purpose programming language
-it supports and simplifies a wide variety of applications, such as
+CUE is an
+<dfn title='License: "Apache-2.0", DCO: true, CLA: false'>open-source</dfn>
+data validation language with its roots in logic programming.
+It combines succinct yet clear syntax with powerful, flexible constraints that
+enable data, schema, and policy constraints to coexist seamlessly:
+
+{{{with code "en" "example"}}}
+#location left right
+! exec cue vet example.cue
+cmp stderr out
+-- example.cue --
+length: 20 & int
+width:  10.1 & >10 // Must be greater than 10
+area:   length * width
+area:   <=100 // Must be less than or equal to 100
+-- out --
+area: invalid value 202.0 (out of bound <=100):
+    ./example.cue:4:9
+    ./example.cue:3:9
+{{{end}}}
+
+CUE supports and simplifies a wide variety of applications, such as
 [data validation]({{< relref "concept/how-cue-enables-data-validation" >}}),
 [configuration]({{< relref "concept/how-cue-enables-configuration" >}}),
 [querying]({{< relref "docs/concept/querying-use-case" >}}),
-and [code generation]({{< relref "concept/code-generation-and-extraction-use-case" >}}).
+and [code generation]({{< relref "concept/code-generation-and-extraction-use-case" >}}),
+with its underlying inference engine enabling data validation in code, and
+flexible generation pipelines.
 
 <!-- TODO: add when content is expanded: -->
 <!-- [scripting](TODO)       https://github.com/cue-lang/docs-and-content/issues/27 -->
 <!-- [data templating](TODO) https://github.com/cue-lang/docs-and-content/issues/26 -->
 
-The inference engine can be used to validate
-data in code, or to include it as part of a code generation pipeline.
-
 ## How to use this documentation
 
-Select a section from the navigation bar on the left hand side of the page, or
-from this brief explanation of each section:
+Browse through the different documentation sections,
+or use the search box in the top-right corner of each page.
+Here's what you'll find in each section:
 
 {{< cards >}}
 

content/docs/gen_cache.cue

@@ -0,0 +1,14 @@
+package site
+{
+	content: {
+		docs: {
+			page: {
+				cache: {
+					code: {
+						example: "Upd/bTuqJ3DDUc172utkfnh80U7Ks83RbeEMb/dwUAI="
+					}
+				}
+			}
+		}
+	}
+}

hugo/content/en/docs/_index.md

@@ -3,30 +3,49 @@ title: "Documentation"
 index_hide: true
 cascade:
   header_type: wide
+disableNotification: true
 ---
 
 # Welcome to CUE!
 
-CUE is an open-source data validation language and inference engine
-with its roots in logic programming.
-Although the language is not a general-purpose programming language
-it supports and simplifies a wide variety of applications, such as
+CUE is an
+<dfn title='License: "Apache-2.0", DCO: true, CLA: false'>open-source</dfn>
+data validation language with its roots in logic programming.
+It combines succinct yet clear syntax with powerful, flexible constraints that
+enable data, schema, and policy constraints to coexist seamlessly:
+
+{{< code-tabs >}}
+{{< code-tab name="example.cue" language="cue" area="left" >}}
+length: 20 & int
+width:  10.1 & >10 // Must be greater than 10
+area:   length * width
+area:   <=100 // Must be less than or equal to 100
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" area="right" type="terminal" codetocopy="Y3VlIHZldCBleGFtcGxlLmN1ZQ==" >}}
+$ cue vet example.cue
+area: invalid value 202.0 (out of bound <=100):
+    ./example.cue:4:9
+    ./example.cue:3:9
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+CUE supports and simplifies a wide variety of applications, such as
 [data validation]({{< relref "concept/how-cue-enables-data-validation" >}}),
 [configuration]({{< relref "concept/how-cue-enables-configuration" >}}),
 [querying]({{< relref "docs/concept/querying-use-case" >}}),
-and [code generation]({{< relref "concept/code-generation-and-extraction-use-case" >}}).
+and [code generation]({{< relref "concept/code-generation-and-extraction-use-case" >}}),
+with its underlying inference engine enabling data validation in code, and
+flexible generation pipelines.
 
 <!-- TODO: add when content is expanded: -->
 <!-- [scripting](TODO)       https://github.com/cue-lang/docs-and-content/issues/27 -->
 <!-- [data templating](TODO) https://github.com/cue-lang/docs-and-content/issues/26 -->
 
-The inference engine can be used to validate
-data in code, or to include it as part of a code generation pipeline.
-
 ## How to use this documentation
 
-Select a section from the navigation bar on the left hand side of the page, or
-from this brief explanation of each section:
+Browse through the different documentation sections,
+or use the search box in the top-right corner of each page.
+Here's what you'll find in each section:
 
 {{< cards >}}