docs/*: use hugo's "relref" wherever possible

This change makes sure that all markdown links that point towards
another page on the site use Hugo's "relref" shortcode to resolve the
target. cf. https://gohugo.io/content-management/cross-references/

This is done primarily to enforce build-time target-page existence
checking. Whilst Hugo doesn't appear to be able to check that the target
page contains the specific *fragment* being linked to, it does check
that the page exists.

Hugo's docs suggest that one can/should use it to point to a literal
file on disk, but we use it to point to the containing directory because
it works, and:
1. the file that Hugo sees and would need to have mentioned (index.md)
   is different from the one that our authors see in the content/
   hierarchy ($lang.md); and
2. we currently store a single content file per directory, so there's no
   ambiguity or corner case where we might need to link to a /specific/
   file in a directory.

This also updates a few relref arguments to be relative (i.e. not
starting with "/") from their current, absolute, form, for consistency.
We can revisit this as & when required.

Preview-Path: /docs/concept/code-generation-and-extraction-use-case/
Preview-Path: /docs/concept/data-validation-use-case/
Preview-Path: /docs/concept/modules-packages-instances/
Preview-Path: /docs/concept/schema-definition-use-case/
Preview-Path: /docs/howto/constrain-string-as-valid-integer/
Preview-Path: /docs/howto/constrain-the-length-of-a-string/
Preview-Path: /docs/howto/constrain-the-sum-of-a-list-of-numbers/
Preview-Path: /docs/howto/encode-json-yaml-with-cue/
Preview-Path: /docs/howto/mark-a-field-as-optional/
Preview-Path: /docs/howto/mark-a-field-as-required/
Preview-Path: /docs/howto/specify-a-default-value-for-a-field/
Preview-Path: /docs/howto/transform-json-with-cue/
Preview-Path: /docs/howto/transform-yaml-with-cue/
Preview-Path: /docs/howto/validate-json-using-cue/
Preview-Path: /docs/howto/validate-yaml-using-cue/
Preview-Path: /docs/integration/openapi/
Preview-Path: /docs/language-guide/data/maps-and-fields/
Preview-Path: /docs/language-guide/data/organizing-configuration/
Preview-Path: /docs/tour/
Preview-Path: /docs/tour/basics/next/
Preview-Path: /docs/tour/expressions/next/
Preview-Path: /docs/tour/packages/next/
Preview-Path: /docs/tour/references/next/
Preview-Path: /docs/tour/types/next/
Preview-Path: /docs/tour/types/stringlit/
Preview-Path: /docs/tutorial/validating-simple-yaml-files/
Signed-off-by: Jonathan Matthews <github@hello.jonathanmatthews.com>
Change-Id: Ic0d8080a7f5aaf7d9db4456fd6895453df8bf689
Reviewed-on: https://review.gerrithub.io/c/cue-lang/cuelang.org/+/1173887
TryBot-Result: CUEcueckoo <cueckoo@cuelang.org>
Reviewed-by: Paul Jolly <paul@myitcv.io>

content/docs/concept/code-generation-and-extraction-use-case/en.md

@@ -6,9 +6,8 @@ toc_hide: true
 
 Code generation and extraction is a broad topic and, for instance, overlaps
 with the topics discussed in
-[Schema Definition]({{< relref "/docs/concept/schema-definition-use-case" >}}) and
-[Go](/docs/integrations/go).
-<!-- TODO: update link after integration pages are imported -->
+[Schema Definition]({{< relref "docs/concept/schema-definition-use-case" >}}) and
+[Go]({{< relref "docs/integration/go" >}}).
 
 In this section we emphasize the role of CUE in a code-generation pipeline,
 that is using CUE as an interlingua for the extraction from and the
@@ -24,8 +23,7 @@ one usually already has some code base to deal with.
 
 CUE can currently extract definitions from:
 
-<!-- TODO: update link after integration pages are imported -->
-- [Go code](/docs/integrations/go#extract-cue-from-go)
+- [Go code]({{< relref "docs/integration/go#extract-cue-from-go" >}})
 - Protobuf definitions.
 
 Moreover, CUE can combine and reduce the constraints from various sources

content/docs/concept/data-validation-use-case/en.md

@@ -91,9 +91,8 @@ Using CUE to generate the schema has several advantages over doing so directly:
 
 ### Migration path
 
-<!-- TODO: update URL -->
 As discussed in
-["Be useful at all scales"](/docs/about#be-useful-at-all-scales),
+["Be useful at all scales"]({{< relref "docs/introduction#be-useful-at-all-scales" >}}),
 there is a high cost to changing languages as one reaches the limits
 with a certain approach.
 
@@ -137,4 +136,4 @@ Such a thing is not possible in JSON schema (or most configuration languages
 for that matter).
 
 More on JSON Schema and its subset, OpenAPI,
-in [Schema Definition]({{< relref "/docs/concept/schema-definition-use-case#json-schema--openapi" >}}).
+in [Schema Definition]({{< relref "docs/concept/schema-definition-use-case#json-schema--openapi" >}}).

content/docs/concept/modules-packages-instances/en.md

@@ -107,7 +107,7 @@ predominantly managed by the `cue` tool.
 
 The `module.cue` file defines settings such as
 globally unique _module identifier_ (more on this in the
-[Import Path](#ImportPath) section).
+[Import Path]({{< relref "#ImportPath" >}}) section).
 This information allows packages defined within the module to be importable
 within the module itself.
 In the future, it may hold version information of imported packages to determine

content/docs/concept/schema-definition-use-case/en.md

@@ -132,7 +132,8 @@ say, human consumption.
 CUE's logical inference engine automatically reduces constraints.
 Its API makes it possible to compute and select between
 various normal forms to optimize for a certain representation.
-This is used in [CUE's OpenAPI generator](/docs/integrations/openapi), <!-- TODO: Update URL -->
+This is used in
+[CUE's OpenAPI generator]({{< relref "docs/integration/openapi" >}}),
 for instance.
 
 

content/docs/howto/constrain-string-as-valid-integer/en.md

@@ -15,8 +15,9 @@ relatedIssues:
 toc_hide: true
 ---
 
-This [Commented CUE](/search/?q=tag:"commented%20cue") demonstrates howto
-constrain a field to contain a string representations of integer values.
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to constrain fields to contain string representations of
+integer values.
 
 {{{with code "en" "example"}}}
 ! exec cue vet .:example data.yml

content/docs/howto/constrain-the-length-of-a-string/en.md

@@ -12,7 +12,7 @@ relatedIssues:
 toc_hide: true
 ---
 
-This [Commented CUE](/docs/howto/about-these-guides/#commented-cue-guides)
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
 demonstrates how to make sure a string has a minimum length, or a maximum
 length, or both.
 

content/docs/howto/constrain-the-sum-of-a-list-of-numbers/en.md

@@ -14,7 +14,7 @@ relatedIssues:
 toc_hide: true
 ---
 
-This [Commented CUE](/docs/howto/about-these-guides/#commented-cue-guides)
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
 demonstrates constraining the sum of a list of numbers.
 
 {{{with code "en" "cc"}}}

content/docs/howto/encode-json-yaml-with-cue/en.md

@@ -24,10 +24,10 @@ accomplish that with the `cue` command line. First with JSON, then with YAML.
 
 ### Prerequisites
 
--   You have [CUE installed](https://cuelang.org/docs/install/) locally. This
-    allows you to run `cue` commands
--   You know how to use [CUE Definitions/ Helper Fields]({{< ref
-    "/docs/language-guide/data" >}})
+-   You have [CUE installed]({{< relref "docs/introduction/installation" >}})
+    locally. This allows you to run `cue` commands
+-   You know how to use
+    [CUE Definitions/ Helper Fields]({{< relref "docs/language-guide/data" >}})
 
 {{< /spotlight >}}
 

content/docs/howto/mark-a-field-as-optional/en.md

@@ -12,7 +12,7 @@ relatedIssues:
 toc_hide: true
 ---
 
-This [Commented CUE](/docs/howto/about-these-guides/#commented-cue-guides)
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
 demonstrates using an **optional field** marker to constrain a field's value -
 *but only if it is present*.
 
@@ -61,13 +61,13 @@ s1:
 
 ## Related content
 
-- [**Optional field constraints**]({{< ref
+- [**Optional field constraints**]({{< relref
     "docs/language-guide/schemas-and-validation/field-constraints#optional-field-constraints"
   >}})
-- [**Regular fields**]({{< ref
+- [**Regular fields**]({{< relref
     "docs/language-guide/data/maps-and-fields#field-names"
   >}})
-- [**Value constraints**]({{< ref
+- [**Value constraints**]({{< relref
     "docs/language-guide/schemas-and-validation/value-constraints"
   >}})
 - [**Commented CUE guides**]({{< relref

content/docs/howto/mark-a-field-as-required/en.md

@@ -12,7 +12,7 @@ relatedIssues:
 toc_hide: true
 ---
 
-This [Commented CUE](/docs/howto/about-these-guides/#commented-cue-guides)
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
 demonstrates using the **required field** marker in a schema to make sure that a
 field is present in data.
 
@@ -48,4 +48,6 @@ s1:
 
 ## Related content
 
-- [**Required field constraints**]({{< ref "docs/language-guide/schemas-and-validation/field-constraints#required-field-constraints" >}})
+- [**Required field constraints**]({{< relref
+    "docs/language-guide/schemas-and-validation/field-constraints#required-field-constraints"
+  >}})

content/docs/howto/specify-a-default-value-for-a-field/en.md

@@ -285,19 +285,19 @@ overriding values.
 
 ## See also
 
-- [**Default values**]({{< ref
+- [**Default values**]({{< relref
     "docs/language-guide/schemas-and-validation/disjunctions#default-values"
   >}})
-- [**Disjunctions**]({{< ref
+- [**Disjunctions**]({{< relref
     "docs/language-guide/schemas-and-validation/disjunctions"
   >}})
 <!-- - [**Unification**](TODO) -->
-- [**Field constraints**]({{< ref
+- [**Field constraints**]({{< relref
     "docs/language-guide/schemas-and-validation/field-constraints"
   >}})
-- [**Value constraints**]({{< ref
+- [**Value constraints**]({{< relref
     "docs/language-guide/schemas-and-validation/value-constraints"
   >}})
-- [**Regular fields**]({{< ref
+- [**Regular fields**]({{< relref
     "docs/language-guide/data/maps-and-fields#field-names"
   >}})

content/docs/howto/transform-json-with-cue/en.md

@@ -8,7 +8,7 @@ authors:
 toc_hide: true
 ---
 
-This [Commented CUE](/docs/howto/about-these-guides/#commented-cue-guides)
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
 demonstrates how to transform JSON by reshaping some input data into different
 output.
 

content/docs/howto/transform-yaml-with-cue/en.md

@@ -8,7 +8,7 @@ authors:
 toc_hide: true
 ---
 
-This [Commented CUE](/docs/howto/about-these-guides/#commented-cue-guides)
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
 demonstrates how to transform YAML by reshaping some input data into different
 output.
 

content/docs/howto/validate-json-using-cue/en.md

@@ -16,9 +16,10 @@ command line.
 
 ## Prerequisites
 
--   You have [CUE installed](https://cuelang.org/docs/install/) locally. This
-    allows you to run `cue` commands
--   You know how to use [CUE Definitions/ Helper Fields]({{< ref "/docs/language-guide/data" >}})
+-   You have [CUE installed]({{< relref "docs/introduction/installation" >}})
+    locally. This allows you to run `cue` commands
+-   You know how to use
+    [CUE Definitions/ Helper Fields]({{< relref "docs/language-guide/data" >}})
 
 ## Requirements
 

content/docs/howto/validate-yaml-using-cue/en.md

@@ -16,9 +16,10 @@ value in a YAML file is the _data type_ it's supposed to be, using the CUE comma
 
 ## Prerequisites
 
-- You have [CUE installed](https://cuelang.org/docs/install/) locally. This
-allows you to run `cue` commands
-- You know how to use [CUE Definitions/ Helper Fields]({{< ref "/docs/language-guide/data" >}})
+-   You have [CUE installed]({{< relref "docs/introduction/installation" >}})
+    locally. This allows you to run `cue` commands
+-   You know how to use
+    [CUE Definitions/ Helper Fields]({{< relref "docs/language-guide/data" >}})
 
 ## Requirements
 

content/docs/integration/openapi/en.md

@@ -7,9 +7,9 @@ toc_hide: false
 
 OpenAPI is a standard for the description of REST APIs.
 Describing value schema is one aspect of this.
-<!-- TODO: Update URL -->
-In the [Schema Definition](/docs/usecases/datadef) section we already
-talked about the relationship between CUE and OpenAPI.
+In the
+[Schema Definition]({{< relref "docs/concept/schema-definition-use-case" >}})
+section we already talked about the relationship between CUE and OpenAPI.
 
 One aspect of OpenAPI is to define data schema.
 CUE supports converting CUE values to such schema.

content/docs/language-guide/data/maps-and-fields/en.md

@@ -14,8 +14,7 @@ Double quotes can be omitted if the name is a valid {{{def "identifier"}}}
 that starts with a letter or `$` and otherwise only contains letters, digits,
 `$` or `_`.
 Identifiers may also start with `#` or `_`, in which case the field is a
-[[Helper fields](Data%201b448a6f417b4e08b2d41b3b33cf2a45.md)](helper field) with
-special meaning.
+[helper field]({{< relref "#helper-field" >}}) with special meaning.
 
 {{{with code "en" "field-names-double-quotes"}}}
 -- in.cue --
@@ -69,7 +68,7 @@ to define helper fields.
 
 Helper fields allow reuse of CUE code when composing larger configurations.
 More on this in the
-[Templating](Templating%20f4e21af73d744a77aa2c91203a8dbe4f.md) section.
+[Templating]({{< relref "docs/language-guide/templating" >}}) section.
 
 {{{with code "en" "helper-fields"}}}
 -- in.cue --

content/docs/language-guide/data/organizing-configuration/en.md

@@ -68,7 +68,8 @@ list: [1, 2, 3, 4]
 As can be seen, identical fields do not have to be placed next to each other.
 
 Merging is also used for validation.
-More on this in [Schemas and Validation](Schemas%20and%20Validation%20b39455d56fdb433ba9ea59c04a2dcece.md).
+More on this in
+[Schemas and Validation]({{< relref "docs/language-guide/schemas-and-validation" >}}).
 
 ## Single-field shorthand
 
@@ -142,4 +143,4 @@ another file.
 If there are multiple packages in a directory, CUE will default to the package
 with the same name as the directory.
 
-[File Organization](File%20Organization%207692931315a445acb9634b91b2b397f0.md)
+[File Organization]({{< relref "docs/language-guide/file-organization" >}})

content/docs/tour/_en.md

@@ -30,5 +30,5 @@ index_hide: true
 
 *This tour of CUE is being actively developed, and its contents may migrate
 into other sections of the CUE documentation site over time. In particular the
-[Language Guide]({{< relref "language-guide.md" >}}) will provide a deep dive
-into CUE, covering many of the topics currently included here.*
+[Language Guide]({{< relref "docs/language-guide" >}}) will provide a deep
+dive into CUE, covering many of the topics currently included here.*

content/docs/tour/packages/next/en.md

@@ -5,7 +5,7 @@ weight: 1000
 
 You've reached the end of this tour through CUE. Next, you could:
 
-- [Install the `cue` CLI]({{< relref "docs/introduction/installation#install-cue-from-official-release-binaries" >}})
+- [Install the `cue` CLI]({{< relref "docs/introduction/installation" >}})
   and try out CUE on your computer
 - Read the [Language Guide]({{< relref "docs/language-guide" >}}) for a deeper
   dive into CUE's features and capabilities

content/docs/tour/types/stringlit/en.md

@@ -11,8 +11,8 @@ The closing quote must also be on a newline.
 The whitespace directly preceding the closing quote must match the preceding
 whitespace on all other lines and is removed from these lines.
 
-Strings may also contain [interpolations](../../expressions/interpolation).
-<!-- FIXME: update interpolations link -->
+Strings may also contain
+[interpolations]({{< relref "../../expressions/interpolation" >}})).
 
 
 {{{with code "en" "stringlit"}}}

content/docs/tutorial/_en.md

@@ -14,8 +14,8 @@ To discover the range of tutorials that are available, use the
 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
+[CUE Tour]({{< relref "tour" >}}) and
+[Language Guide]({{< relref "docs/language-guide" >}}), and then try out some
 tutorials specifically selected for you on the
 ["New to CUE?"]({{< relref "new-to-cue" >}}) page.
 

content/docs/tutorial/validating-simple-yaml-files/en.md

@@ -40,8 +40,8 @@ Call out only-tested-on-Linuxness?
 ## Install the `cue` command
 
 {{{with step}}}
-If you have not already, follow the steps for [downloading and installing
-CUE]({{< ref "docs/introduction/installation" >}}).
+If you have not already, follow the steps for
+[downloading and installing CUE]({{< relref "docs/introduction/installation" >}}).
 {{{end}}}
 
 ## Validate a single data file

hugo/content/en/docs/concept/code-generation-and-extraction-use-case/index.md

@@ -6,9 +6,8 @@ toc_hide: true
 
 Code generation and extraction is a broad topic and, for instance, overlaps
 with the topics discussed in
-[Schema Definition]({{< relref "/docs/concept/schema-definition-use-case" >}}) and
-[Go](/docs/integrations/go).
-<!-- TODO: update link after integration pages are imported -->
+[Schema Definition]({{< relref "docs/concept/schema-definition-use-case" >}}) and
+[Go]({{< relref "docs/integration/go" >}}).
 
 In this section we emphasize the role of CUE in a code-generation pipeline,
 that is using CUE as an interlingua for the extraction from and the
@@ -24,8 +23,7 @@ one usually already has some code base to deal with.
 
 CUE can currently extract definitions from:
 
-<!-- TODO: update link after integration pages are imported -->
-- [Go code](/docs/integrations/go#extract-cue-from-go)
+- [Go code]({{< relref "docs/integration/go#extract-cue-from-go" >}})
 - Protobuf definitions.
 
 Moreover, CUE can combine and reduce the constraints from various sources

hugo/content/en/docs/concept/data-validation-use-case/index.md

@@ -90,9 +90,8 @@ Using CUE to generate the schema has several advantages over doing so directly:
 
 ### Migration path
 
-<!-- TODO: update URL -->
 As discussed in
-["Be useful at all scales"](/docs/about#be-useful-at-all-scales),
+["Be useful at all scales"]({{< relref "docs/introduction#be-useful-at-all-scales" >}}),
 there is a high cost to changing languages as one reaches the limits
 with a certain approach.
 
@@ -135,4 +134,4 @@ Such a thing is not possible in JSON schema (or most configuration languages
 for that matter).
 
 More on JSON Schema and its subset, OpenAPI,
-in [Schema Definition]({{< relref "/docs/concept/schema-definition-use-case#json-schema--openapi" >}}).
+in [Schema Definition]({{< relref "docs/concept/schema-definition-use-case#json-schema--openapi" >}}).

hugo/content/en/docs/concept/modules-packages-instances/index.md

@@ -105,7 +105,7 @@ predominantly managed by the `cue` tool.
 
 The `module.cue` file defines settings such as
 globally unique _module identifier_ (more on this in the
-[Import Path](#ImportPath) section).
+[Import Path]({{< relref "#ImportPath" >}}) section).
 This information allows packages defined within the module to be importable
 within the module itself.
 In the future, it may hold version information of imported packages to determine

hugo/content/en/docs/concept/schema-definition-use-case/index.md

@@ -129,7 +129,8 @@ say, human consumption.
 CUE's logical inference engine automatically reduces constraints.
 Its API makes it possible to compute and select between
 various normal forms to optimize for a certain representation.
-This is used in [CUE's OpenAPI generator](/docs/integrations/openapi), <!-- TODO: Update URL -->
+This is used in
+[CUE's OpenAPI generator]({{< relref "docs/integration/openapi" >}}),
 for instance.
 
 

hugo/content/en/docs/howto/constrain-string-as-valid-integer/index.md

@@ -15,8 +15,9 @@ relatedIssues:
 toc_hide: true
 ---
 
-This [Commented CUE](/search/?q=tag:"commented%20cue") demonstrates howto
-constrain a field to contain a string representations of integer values.
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to constrain fields to contain string representations of
+integer values.
 
 {{< code-tabs >}}
 {{< code-tab name="example.cue" language="cue"  area="top-left" >}}

hugo/content/en/docs/howto/constrain-the-length-of-a-string/index.md

@@ -12,7 +12,7 @@ relatedIssues:
 toc_hide: true
 ---
 
-This [Commented CUE](/docs/howto/about-these-guides/#commented-cue-guides)
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
 demonstrates how to make sure a string has a minimum length, or a maximum
 length, or both.