From 16bc4e50f2333a5d4352898a5442b41edd858f18 Mon Sep 17 00:00:00 2001 From: Jonathan Matthews Date: Tue, 13 Feb 2024 09:03:01 +0000 Subject: [PATCH] hugo: shortcode linkto/related/* This adds 4 shortcodes that generate consistently formatted links to concept guides, howto guides, references, and tutorials. Their formatted output is intended for use inside pages' Related content sections, with the intention to replace all current manually-formatted links in these sections with uses of these shortcodes, site wide. Preview-Path: /examples/shortcodes/linkto/ Signed-off-by: Jonathan Matthews Change-Id: Ia74ca0e8eca3c8e1e1d9dc0f35e16ccac87075e2 Dispatch-Trailer: {"type":"trybot","CL":1176797,"patchset":1,"ref":"refs/changes/97/1176797/1","targetBranch":"alpha"} --- content/examples/_en.html | 15 ++++--- content/examples/shortcodes/linkto/en.md | 40 +++++++++++++++++++ content/examples/shortcodes/linkto/page.cue | 3 ++ hugo/content/en/examples/_index.html | 15 ++++--- .../en/examples/shortcodes/linkto/index.md | 40 +++++++++++++++++++ .../shortcodes/linkto/related/concept.html | 9 +++++ .../shortcodes/linkto/related/howto.html | 9 +++++ .../shortcodes/linkto/related/reference.html | 9 +++++ .../shortcodes/linkto/related/tutorial.html | 9 +++++ 9 files changed, 139 insertions(+), 10 deletions(-) create mode 100644 content/examples/shortcodes/linkto/en.md create mode 100644 content/examples/shortcodes/linkto/page.cue create mode 100644 hugo/content/en/examples/shortcodes/linkto/index.md create mode 100644 hugo/layouts/shortcodes/linkto/related/concept.html create mode 100644 hugo/layouts/shortcodes/linkto/related/howto.html create mode 100644 hugo/layouts/shortcodes/linkto/related/reference.html create mode 100644 hugo/layouts/shortcodes/linkto/related/tutorial.html diff --git a/content/examples/_en.html b/content/examples/_en.html index c3050d6e7e..e6177be902 100644 --- a/content/examples/_en.html +++ b/content/examples/_en.html @@ -100,11 +100,21 @@

Examples

Shortcodes

diff --git a/content/examples/shortcodes/linkto/en.md b/content/examples/shortcodes/linkto/en.md new file mode 100644 index 0000000000..1592181288 --- /dev/null +++ b/content/examples/shortcodes/linkto/en.md @@ -0,0 +1,40 @@ +--- +title: linkto +--- + +The `linkto` hierarchy contains convenience shims that generate well-formed and +consistently formatted links to commonly referenced pages. + +### `linkto/related/{concept,howto,reference,tutorial}` + +`linkto/related/` contains 4 shortcodes primarily aimed at generating links to +Tutorials, How-to Guides, Concept Guides, and References. The links contain the +linked-to page's title field. They are intended to be used in a page's "Related +content" section, placed inside a list element. They only generate content +suitable for inclusion in a list, and do not generate self-contained list +elements. + +Only these 4 hierarchies are currently supported as they make up the majority +of related content links, and have reduced implementation complexity (relative +to, say, linking to the Language Guide or the Tour) due to their flat page +hierarchies. + +#### Parameters + +The first positional parameter is the path component of the related page +**within** the relevant hierarchy. I.e. **without** a leading "docs/tutorial/", +"docs/reference/", etc. + +#### Examples + +``` +- {{}} +- {{}} +- {{}} +- {{}} +``` + +- {{< linkto/related/concept "the-logic-of-cue" >}} +- {{< linkto/related/howto "use-strings-replace" >}} +- {{< linkto/related/reference "modules" >}} +- {{< linkto/related/tutorial "working-with-a-custom-module-registry" >}} diff --git a/content/examples/shortcodes/linkto/page.cue b/content/examples/shortcodes/linkto/page.cue new file mode 100644 index 0000000000..0a00ad33ac --- /dev/null +++ b/content/examples/shortcodes/linkto/page.cue @@ -0,0 +1,3 @@ +package site + +content: examples: shortcodes: linkto: {} diff --git a/hugo/content/en/examples/_index.html b/hugo/content/en/examples/_index.html index c3050d6e7e..e6177be902 100644 --- a/hugo/content/en/examples/_index.html +++ b/hugo/content/en/examples/_index.html @@ -100,11 +100,21 @@

Examples

Shortcodes

diff --git a/hugo/content/en/examples/shortcodes/linkto/index.md b/hugo/content/en/examples/shortcodes/linkto/index.md new file mode 100644 index 0000000000..1592181288 --- /dev/null +++ b/hugo/content/en/examples/shortcodes/linkto/index.md @@ -0,0 +1,40 @@ +--- +title: linkto +--- + +The `linkto` hierarchy contains convenience shims that generate well-formed and +consistently formatted links to commonly referenced pages. + +### `linkto/related/{concept,howto,reference,tutorial}` + +`linkto/related/` contains 4 shortcodes primarily aimed at generating links to +Tutorials, How-to Guides, Concept Guides, and References. The links contain the +linked-to page's title field. They are intended to be used in a page's "Related +content" section, placed inside a list element. They only generate content +suitable for inclusion in a list, and do not generate self-contained list +elements. + +Only these 4 hierarchies are currently supported as they make up the majority +of related content links, and have reduced implementation complexity (relative +to, say, linking to the Language Guide or the Tour) due to their flat page +hierarchies. + +#### Parameters + +The first positional parameter is the path component of the related page +**within** the relevant hierarchy. I.e. **without** a leading "docs/tutorial/", +"docs/reference/", etc. + +#### Examples + +``` +- {{}} +- {{}} +- {{}} +- {{}} +``` + +- {{< linkto/related/concept "the-logic-of-cue" >}} +- {{< linkto/related/howto "use-strings-replace" >}} +- {{< linkto/related/reference "modules" >}} +- {{< linkto/related/tutorial "working-with-a-custom-module-registry" >}} diff --git a/hugo/layouts/shortcodes/linkto/related/concept.html b/hugo/layouts/shortcodes/linkto/related/concept.html new file mode 100644 index 0000000000..fb61a30aea --- /dev/null +++ b/hugo/layouts/shortcodes/linkto/related/concept.html @@ -0,0 +1,9 @@ +{{ $relPath := printf "docs/concept/%s" (.Get 0) -}} +{{ $linkToPage := site.GetPage $relPath -}} +{{- if eq (strings.CountRunes $linkToPage.Title) 0 -}} + {{ errorf "[%s] %q: %q not found or has no title" site.Language.Lang .Page.File $relPath }} +{{- end -}} +Concept Guide: {{ with $linkToPage -}} + {{- $opts := dict "path" $relPath -}} + {{ .Title }} +{{- end}} diff --git a/hugo/layouts/shortcodes/linkto/related/howto.html b/hugo/layouts/shortcodes/linkto/related/howto.html new file mode 100644 index 0000000000..56546c7a9d --- /dev/null +++ b/hugo/layouts/shortcodes/linkto/related/howto.html @@ -0,0 +1,9 @@ +{{ $relPath := printf "docs/howto/%s" (.Get 0) -}} +{{ $linkToPage := site.GetPage $relPath -}} +{{- if eq (strings.CountRunes $linkToPage.Title) 0 -}} + {{ errorf "[%s] %q: %q not found or has no title" site.Language.Lang .Page.File $relPath }} +{{- end -}} +How-to Guide: {{ with $linkToPage -}} + {{- $opts := dict "path" $relPath -}} + {{ .Title }} +{{- end}} diff --git a/hugo/layouts/shortcodes/linkto/related/reference.html b/hugo/layouts/shortcodes/linkto/related/reference.html new file mode 100644 index 0000000000..929bc0c92c --- /dev/null +++ b/hugo/layouts/shortcodes/linkto/related/reference.html @@ -0,0 +1,9 @@ +{{ $relPath := printf "docs/reference/%s" (.Get 0) -}} +{{ $linkToPage := site.GetPage $relPath -}} +{{- if eq (strings.CountRunes $linkToPage.Title) 0 -}} + {{ errorf "[%s] %q: %q not found or has no title" site.Language.Lang .Page.File $relPath }} +{{- end -}} +Reference: {{ with $linkToPage -}} + {{- $opts := dict "path" $relPath -}} + {{ .Title }} +{{- end}} diff --git a/hugo/layouts/shortcodes/linkto/related/tutorial.html b/hugo/layouts/shortcodes/linkto/related/tutorial.html new file mode 100644 index 0000000000..0597605d8f --- /dev/null +++ b/hugo/layouts/shortcodes/linkto/related/tutorial.html @@ -0,0 +1,9 @@ +{{ $relPath := printf "docs/tutorial/%s" (.Get 0) -}} +{{ $linkToPage := site.GetPage $relPath -}} +{{- if eq (strings.CountRunes $linkToPage.Title) 0 -}} + {{ errorf "[%s] %q: %q not found or has no title" site.Language.Lang .Page.File $relPath }} +{{- end -}} +Tutorial: {{ with $linkToPage -}} + {{- $opts := dict "path" $relPath -}} + {{ .Title }} +{{- end}}