From 1e51254014f6bae708feee84c8d2af5baa8b7946 Mon Sep 17 00:00:00 2001
From: Jonathan Matthews <github@hello.jonathanmatthews.com>
Date: Fri, 23 Aug 2024 16:50:11 +0100
Subject: [PATCH] docs/reference: add modules landing page

This re-restablishes the path /docs/reference/modules/ by using it to
present a landing page for CUE modules.

A brief introduction provides some context, before leading on to 6 pages
selected to give a rounded impression of the modules-related resources
available to the reader. The landing page is included in the set of
pages which will persist in the LH nav, no matter which Reference
sub-page is being viewed.

The "modules" tag is linked to, instead of providing a dynamic on-page
list of the tagged content, because the search shortcode can't
pre-populate a query with a tag. This is tracked in cue-lang/cue#3394.

Also: the modules reference manual is retitled slightly in order to
provide a clear user experience when linking to it by title from across
the site, and has its "toc_hide: true" removed, so that it persists in
the reference/modules/ section's LH nav even when the guide itself isn't
open.

Preview-Path: /docs/reference/modules/
Preview-Path: /docs/reference/modules/manual/
Preview-Path: /docs/reference/
Signed-off-by: Jonathan Matthews <github@hello.jonathanmatthews.com>
Change-Id: Ia8dc6b1d6e4909469a34200d97ff4f0a2ea6e076
Dispatch-Trailer: {"type":"trybot","CL":1199965,"patchset":3,"ref":"refs/changes/65/1199965/3","targetBranch":"master"}
---
 content/docs/reference/_en.md                 |  2 +-
 content/docs/reference/modules/_en.md         | 57 +++++++++++++++++++
 content/docs/reference/modules/manual/en.md   |  9 +--
 content/docs/reference/modules/page.cue       |  3 +
 hugo/content/en/docs/reference/_index.md      |  2 +-
 .../en/docs/reference/modules/_index.md       | 57 +++++++++++++++++++
 .../en/docs/reference/modules/manual/index.md |  9 +--
 7 files changed, 125 insertions(+), 14 deletions(-)
 create mode 100644 content/docs/reference/modules/_en.md
 create mode 100644 content/docs/reference/modules/page.cue
 create mode 100644 hugo/content/en/docs/reference/modules/_index.md

diff --git a/content/docs/reference/_en.md b/content/docs/reference/_en.md
index 13c966a6d..fa7b9a7fb 100644
--- a/content/docs/reference/_en.md
+++ b/content/docs/reference/_en.md
@@ -16,7 +16,7 @@ Help texts for the `cue` command and its subcommands
 {{< /card >}}
 
 <!-- The trailing "\" on the next line vertically aligns the card's body with the spec card's body -->
-{{< card title="Modules" label="reference/modules" href="modules/manual/" >}}\
+{{< card title="Modules" label="reference/modules" href="modules/" >}}\
 CUE's dependency management system
 {{< /card >}}
 
diff --git a/content/docs/reference/modules/_en.md b/content/docs/reference/modules/_en.md
new file mode 100644
index 000000000..66eba3f9f
--- /dev/null
+++ b/content/docs/reference/modules/_en.md
@@ -0,0 +1,57 @@
+---
+title: CUE Modules
+tags: [modules]
+weight: 60
+index_hide: true
+---
+
+Modules are how CUE manages dependencies
+They must be published to a registry for users to fetch and work with.
+
+Learn about CUE modules using the suggested links below,
+or follow the {{<tag modules>}} tag to explore the full range of modules-related
+pages on the site.
+
+{{<cards>}}
+{{<card title="Reference manual"
+        label="reference/manual"
+        href="manual/"
+>}}
+The CUE modules reference manual and glossary
+{{</card>}}
+
+{{<card title="Concept Guide"
+        label="concept/faq"
+        href="/docs/concept/faq/new-modules-vs-old-modules/"
+>}}
+CUE's "new" versus "old" modules -- your questions: answered
+{{</card>}}
+
+{{<card title="The cue command"
+        label="reference/command/cue"
+        href="/docs/reference/command/cue-help-modules"
+>}}
+The built-in help text for\
+`cue help modules`
+{{</card>}}
+
+{{<card title="Getting started"
+        label="tutorial"
+        href="/docs/tutorial/working-with-the-central-registry/"
+>}}
+Working with the CUE Central Registry
+{{</card>}}
+{{<card title="Collaborate"
+        label="tutorial"
+        href="/docs/tutorial/publishing-modules-to-the-central-registry/"
+>}}
+Publishing modules to the Central Registry
+{{</card>}}
+
+{{<card title="Private infrastructure"
+        label="tutorial"
+        href="/docs/tutorial/working-with-a-custom-module-registry/"
+>}}
+Working with a custom module registry
+{{</card>}}
+{{</cards>}}
diff --git a/content/docs/reference/modules/manual/en.md b/content/docs/reference/modules/manual/en.md
index b9804283d..ecde2e9ef 100644
--- a/content/docs/reference/modules/manual/en.md
+++ b/content/docs/reference/modules/manual/en.md
@@ -1,10 +1,7 @@
 ---
-title: CUE Modules
-authors:
-- rogpeppe
-toc_hide: true
-tags:
-- modules
+title: Modules reference manual
+authors: [rogpeppe]
+tags: [modules]
 ---
 
 ## Introduction {#intro}
diff --git a/content/docs/reference/modules/page.cue b/content/docs/reference/modules/page.cue
new file mode 100644
index 000000000..5ef402818
--- /dev/null
+++ b/content/docs/reference/modules/page.cue
@@ -0,0 +1,3 @@
+package site
+
+content: docs: reference: modules: page: _
diff --git a/hugo/content/en/docs/reference/_index.md b/hugo/content/en/docs/reference/_index.md
index 13c966a6d..fa7b9a7fb 100644
--- a/hugo/content/en/docs/reference/_index.md
+++ b/hugo/content/en/docs/reference/_index.md
@@ -16,7 +16,7 @@ Help texts for the `cue` command and its subcommands
 {{< /card >}}
 
 <!-- The trailing "\" on the next line vertically aligns the card's body with the spec card's body -->
-{{< card title="Modules" label="reference/modules" href="modules/manual/" >}}\
+{{< card title="Modules" label="reference/modules" href="modules/" >}}\
 CUE's dependency management system
 {{< /card >}}
 
diff --git a/hugo/content/en/docs/reference/modules/_index.md b/hugo/content/en/docs/reference/modules/_index.md
new file mode 100644
index 000000000..66eba3f9f
--- /dev/null
+++ b/hugo/content/en/docs/reference/modules/_index.md
@@ -0,0 +1,57 @@
+---
+title: CUE Modules
+tags: [modules]
+weight: 60
+index_hide: true
+---
+
+Modules are how CUE manages dependencies
+They must be published to a registry for users to fetch and work with.
+
+Learn about CUE modules using the suggested links below,
+or follow the {{<tag modules>}} tag to explore the full range of modules-related
+pages on the site.
+
+{{<cards>}}
+{{<card title="Reference manual"
+        label="reference/manual"
+        href="manual/"
+>}}
+The CUE modules reference manual and glossary
+{{</card>}}
+
+{{<card title="Concept Guide"
+        label="concept/faq"
+        href="/docs/concept/faq/new-modules-vs-old-modules/"
+>}}
+CUE's "new" versus "old" modules -- your questions: answered
+{{</card>}}
+
+{{<card title="The cue command"
+        label="reference/command/cue"
+        href="/docs/reference/command/cue-help-modules"
+>}}
+The built-in help text for\
+`cue help modules`
+{{</card>}}
+
+{{<card title="Getting started"
+        label="tutorial"
+        href="/docs/tutorial/working-with-the-central-registry/"
+>}}
+Working with the CUE Central Registry
+{{</card>}}
+{{<card title="Collaborate"
+        label="tutorial"
+        href="/docs/tutorial/publishing-modules-to-the-central-registry/"
+>}}
+Publishing modules to the Central Registry
+{{</card>}}
+
+{{<card title="Private infrastructure"
+        label="tutorial"
+        href="/docs/tutorial/working-with-a-custom-module-registry/"
+>}}
+Working with a custom module registry
+{{</card>}}
+{{</cards>}}
diff --git a/hugo/content/en/docs/reference/modules/manual/index.md b/hugo/content/en/docs/reference/modules/manual/index.md
index b551e0e71..75548230b 100644
--- a/hugo/content/en/docs/reference/modules/manual/index.md
+++ b/hugo/content/en/docs/reference/modules/manual/index.md
@@ -1,10 +1,7 @@
 ---
-title: CUE Modules
-authors:
-- rogpeppe
-toc_hide: true
-tags:
-- modules
+title: Modules reference manual
+authors: [rogpeppe]
+tags: [modules]
 ---
 
 ## Introduction {#intro}