docs/*: replace manual fenced code blocks

This removes several uses of "```" to format code on the page, and
replaces them with "{{{with code ...}}}". This benefits us by increasing
automated "cue fmt" coverage of the examples on the site, and by
engaging syntax highlighting without manual language markers.

Some examples of "```" remain, such as where an environment variable is
being demonstrated; or inside the language guide and spec, which aren't
being updated on the master branch currently.

One example in the modules reference triggers cue-lang/cue#722, and ends
up with a leading comment being incorrectly indented; this issue is
fixed, and the example will have its #nofmt removed after the site is
updated to use CUE v0.10.0 or later.

One page (list-no-duplicates) loses the highlighting of specific lines
in some examples. This is acceptable in light of the changes anticipated
by cue-lang/docs-and-content#171, which are likely to result in this
page being completely rewritten or subsumed into another howto guide.

Preview-Path: /docs/howto/list-no-duplicates/
Preview-Path: /docs/introduction/
Preview-Path: /docs/reference/modules/
Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: I1a15a52ddf979ad6ee44bc8950d5e67892bfeb2f
Reviewed-on: https://review.gerrithub.io/c/cue-lang/cuelang.org/+/1198345
Reviewed-by: Daniel Martí <[email protected]>
TryBot-Result: CUEcueckoo <[email protected]>

content/docs/howto/list-no-duplicates/en.md

@@ -13,22 +13,23 @@ has no duplicate items, use
 
 ## Strings
 
-```{title="CUE"}
+{{{with code "en" "strings"}}}
+-- strings.cue --
 import "list"
 
 items: ["a", "b", "c", "a"]
 items: list.UniqueItems
-```
+{{{end}}}
 
 ## Integers
 
-```{title="CUE"}
-
+{{{with code "en" "ints"}}}
+-- ints.cue --
 import "list"
 
 items: [1, 2, 3, 1]
 items: list.UniqueItems
-```
+{{{end}}}
 
 {{< warning >}}
 Note that this approach does not work correctly on non-integer values.
@@ -44,44 +45,46 @@ To ensure a list of structs has no duplicate keys, one common approach is to
 guarantee that the list has no duplicate items by constructing the list from a
 map.
 
-```txt {title="CUE", hl_lines=["5"]}
+{{{with code "en" "struct from map"}}}
+-- structs.cue --
 _items: {
-	joe: age: 30
+	joe: age:   30
 	alice: age: 35
 }
 _items: [name=string]: "name": name
 
 items: [
 	for item in _items {
 		item
-	}
+	},
 ]
-```
+{{{end}}}
 
 If the list must be constrained directly, you can write an auxiliary field that
 creates a mapping from the keys
 
-```txt {title="CUE", hl_lines=["15"]}
+{{{with code "en" "auxiliary field"}}}
+-- auxiliary-field.cue --
 items: [
 	{
 		name: "joe"
-		age: 30
+		age:  30
 	},
 	{
 		name: "alice"
-		age: 35
+		age:  35
 	},
 	{
 		name: "joe"
-		age: 31
-	}
+		age:  31
+	},
 ]
 _itemsCheck: {
 	for i, item in items {
 		(item.name): i
 	}
 }
-```
+{{{end}}}
 
 If the key is specified twice, there will be a conflict in `_itemsCheck`.
 
@@ -93,34 +96,35 @@ be used, using
 composite string key from the keys. Here, for example, the combination of `name`
 and `dateOfBirth` must be unique:
 
-```txt {title=CUE, hl_lines=["27"]}
+{{{with code "en" "multiple keys"}}}
+-- multiple-keys.cue --
 import "encoding/json"
 
 items: [
 	{
-		name: "joe"
+		name:        "joe"
 		dateOfBirth: "1983-10-21"
-		country: "US"
+		country:     "US"
 	},
 	{
-		name: "alice"
+		name:        "alice"
 		dateOfBirth: "1987-10-15"
-		country: "DE"
+		country:     "DE"
 	},
 	{
-		name: "joe"
+		name:        "joe"
 		dateOfBirth: "2010-02-05"
-		country: "UK"
+		country:     "UK"
 	},
 	{
-		name: "alice"
+		name:        "alice"
 		dateOfBirth: "1987-10-15"
-		country: "BE"
+		country:     "BE"
 	},
 ]
 _itemsCheck: {
 	for i, item in items {
 		(json.Marshal([item.name, item.dateOfBirth])): i
 	}
 }
-```
+{{{end}}}

content/docs/howto/list-no-duplicates/gen_cache.cue

@@ -0,0 +1,22 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"list-no-duplicates": {
+					page: {
+						cache: {
+							code: {
+								strings:           "tUA4fTPKEfvNHRV8lR2+DQ+u7Jep+R1iwOPHmQBNsGc="
+								ints:              "FlhuhgcOgDeEB8phKrYSGuddNzrSJRCH9gFwsSg1lnc="
+								"struct from map": "YVLF55Zn+ViilTYvvbyv+sJIw39SdTz8yU3euB02mMw="
+								"auxiliary field": "gH/VIz4swoyPEZzH7oh1CGX7X1ptmFNUI5eX6ma0Jeg="
+								"multiple keys":   "WUEtLdYf78zDNNuaX3ghuuvGZI0lSl6WF5qZkjzVG3s="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/introduction/_en.md

@@ -186,9 +186,12 @@ All the information of the original JSON file is retained in this
 representation.
 
 CUE generalizes this notion to the following pattern:
-```
+{{{with code "en" "nodes"}}}
+#nofmt
+-- nodes.cue --
 <set of nodes>: <constraints>
-```
+{{{end}}}
+
 Each field declaration in CUE defines a set of nodes to which to apply
 a specific constraint.
 Because order doesn't matter, multiple constraints can be applied to the

content/docs/introduction/gen_cache.cue

@@ -11,6 +11,7 @@ package site
 							CUE:                "sLO2Ri8ghWye87lJpxr3V/QuI27wtBAHUWqpM8dda7g="
 							json:               "8jbyBszvff5B/8klmzMyaWv3LedgbRdX2rkJZedyPiY="
 							"cue form of json": "RXoQoBrKPqsDvrdlM9njOFyvlcY6OuKVUnquP9bPQYU="
+							nodes:              "caxgz6bgHUnXtLhHfRzUQck0kRJbgCgBYe9bxHHdD34="
 							"non-dry":          "Xrcqt8kMmHptu7xrAl3q9aJJYHPf3IMcMja/27ckTSU="
 							dry:                "lyHHjgmAR9WzWrInbMOYtmNN45U9K8CPUGhUd5znE5s="
 						}

content/docs/reference/modules/en.md

@@ -261,7 +261,10 @@ in the host `registry.acme.example` at port 6000.
 A module is defined by a `cue.mod` directory in its root containing
 a `module.cue` CUE file.
 
-```cue
+<!-- TODO(jcm): remove #nofmt after v0.10.0 is released, fixing #722 -->
+{{{with code "en" "module.cue schema"}}}
+#nofmt(schema.cue)
+-- schema.cue --
 // module indicates the module's path.
 module!: #Module
 
@@ -323,11 +326,12 @@ custom?: [#Module | "legacy"]: [_]: _
 	// to determining the list of files in a module.
 	kind!: "self" | "git"
 }
-```
+{{{end}}}
 
 For example:
 
-```cue
+{{{with code "en" "module.cue example"}}}
+-- example.cue --
 language: version: "v0.4.3"
 
 module: "foo.example/my/thing@v1"
@@ -336,7 +340,7 @@ deps: {
 	"foo.example/other/thing@v1": v: "v1.0.2"
 	"foo.example/new/thing@v2": v:   "v2.3.4"
 }
-```
+{{{end}}}
 
 The `module.cue` file is designed to be human readable and machine writable. The
 `cue` command will provide several subcommands that manipulate `cue.mod/module.cue` files.

content/docs/reference/modules/gen_cache.cue

@@ -0,0 +1,19 @@
+package site
+{
+	content: {
+		docs: {
+			reference: {
+				modules: {
+					page: {
+						cache: {
+							code: {
+								"module.cue schema":  "uJoDP+C60NnJWdKp3+GaPNkgmYAupxIjfBdVM+8lzAo="
+								"module.cue example": "ErBNI5DX2Nx+54qTxPdnaD8TKQeCHPhcLD+LQW7apv0="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

hugo/content/en/docs/howto/list-no-duplicates/index.md

@@ -13,7 +13,7 @@ has no duplicate items, use
 
 ## Strings
 
-```{title="CUE"}
+```cue
 import "list"
 
 items: ["a", "b", "c", "a"]
@@ -22,8 +22,7 @@ items: list.UniqueItems
 
 ## Integers
 
-```{title="CUE"}
-
+```cue
 import "list"
 
 items: [1, 2, 3, 1]
@@ -44,37 +43,37 @@ To ensure a list of structs has no duplicate keys, one common approach is to
 guarantee that the list has no duplicate items by constructing the list from a
 map.
 
-```txt {title="CUE", hl_lines=["5"]}
+```cue
 _items: {
-	joe: age: 30
+	joe: age:   30
 	alice: age: 35
 }
 _items: [name=string]: "name": name
 
 items: [
 	for item in _items {
 		item
-	}
+	},
 ]
 ```
 
 If the list must be constrained directly, you can write an auxiliary field that
 creates a mapping from the keys
 
-```txt {title="CUE", hl_lines=["15"]}
+```cue
 items: [
 	{
 		name: "joe"
-		age: 30
+		age:  30
 	},
 	{
 		name: "alice"
-		age: 35
+		age:  35
 	},
 	{
 		name: "joe"
-		age: 31
-	}
+		age:  31
+	},
 ]
 _itemsCheck: {
 	for i, item in items {
@@ -93,29 +92,29 @@ be used, using
 composite string key from the keys. Here, for example, the combination of `name`
 and `dateOfBirth` must be unique:
 
-```txt {title=CUE, hl_lines=["27"]}
+```cue
 import "encoding/json"
 
 items: [
 	{
-		name: "joe"
+		name:        "joe"
 		dateOfBirth: "1983-10-21"
-		country: "US"
+		country:     "US"
 	},
 	{
-		name: "alice"
+		name:        "alice"
 		dateOfBirth: "1987-10-15"
-		country: "DE"
+		country:     "DE"
 	},
 	{
-		name: "joe"
+		name:        "joe"
 		dateOfBirth: "2010-02-05"
-		country: "UK"
+		country:     "UK"
 	},
 	{
-		name: "alice"
+		name:        "alice"
 		dateOfBirth: "1987-10-15"
-		country: "BE"
+		country:     "BE"
 	},
 ]
 _itemsCheck: {

hugo/content/en/docs/introduction/_index.md

@@ -181,9 +181,10 @@ All the information of the original JSON file is retained in this
 representation.
 
 CUE generalizes this notion to the following pattern:
-```
+```cue
 <set of nodes>: <constraints>
 ```
+
 Each field declaration in CUE defines a set of nodes to which to apply
 a specific constraint.
 Because order doesn't matter, multiple constraints can be applied to the

hugo/content/en/docs/reference/modules/index.md

@@ -261,6 +261,7 @@ in the host `registry.acme.example` at port 6000.
 A module is defined by a `cue.mod` directory in its root containing
 a `module.cue` CUE file.
 
+<!-- TODO(jcm): remove #nofmt after v0.10.0 is released, fixing #722 -->
 ```cue
 // module indicates the module's path.
 module!: #Module