shortcode 'blocks/cover': improvements

- use Hugo's native support for processing HTML & markdown (#906) - drop support for pre-Hugo-0.54.x behavior of {{% %}} #939
google · Nov 20, 2023 · 411c512 · 411c512
1 parent 89dd0e2
commit 411c512
Show file tree

Hide file tree

Showing 2 changed files with 52 additions and 36 deletions.
diff --git a/layouts/shortcodes/blocks/cover.html b/layouts/shortcodes/blocks/cover.html
@@ -1,13 +1,18 @@
-{{ $_hugo_config := `{ "version": 1 }` -}}
 {{ $blockID := printf "td-cover-block-%d" .Ordinal -}}
 {{ $promo_image := (.Page.Resources.ByType "image").GetMatch "**background*" -}}
 {{ $logo_image := (.Page.Resources.ByType "image").GetMatch "**logo*" -}}
 {{ $col_id := .Get "color" | default "dark" -}}
 {{ $image_anchor := .Get "image_anchor" | default "smart" -}}
 {{ $logo_anchor := .Get "logo_anchor" | default "smart" -}}
-{{/* Height can be one of: auto, min, med, max, full. */ -}}
-{{ $height := .Get "height" | default "max" -}}
-
+{{ $height := "max" -}}
+{{/* Check: height must be one of: auto, min, med, max, full. */ -}}
+{{ with .Get "height" -}}
+{{ if not ( or ( eq . "auto" ) ( eq . "min" ) ( eq . "med" ) ( eq . "max" ) ( eq . "full" ) ) -}}
+{{ errorf "shortcode 'blocks/cover': parameter height is '%s', must be one of 'auto', 'min', 'med', 'max' or 'full'." . -}}
+{{ else -}}
+{{ $height = . -}}
+{{ end -}}
+{{ end -}}
 {{ with $promo_image -}}
 {{ $promo_image_big := (.Fill (printf "1920x1080 %s" $image_anchor)) -}}
 {{ $promo_image_small := (.Fill (printf "960x540 %s" $image_anchor)) -}}
@@ -25,26 +30,36 @@
 </style>
 {{ end -}}
 
-<section id="{{ $blockID }}" class="row td-cover-block td-cover-block--height-{{ $height -}}
-  {{ if not .Site.Params.ui.navbar_translucent_over_cover_disable }} js-td-cover
-  {{- end }} td-overlay td-overlay--dark -bg-{{ $col_id }}">
-  <div class="col-12">
-    <div class="container td-overlay__inner">
-      <div class="text-center">
-        {{ with .Get "title" }}<h1 class="display-1 mt-0 mt-md-5 pb-4">{{ $title := . }}{{ with $logo_image }}{{ $logo_image_resized := (.Fit (printf "70x70 %s" $logo_anchor)) }}<img class="td-cover-logo" src="{{ $logo_image_resized.RelPermalink }}" alt="{{ $title | html }} Logo">{{ end }}{{ $title | html }}</h1>{{ end }}
-        {{ with .Get "subtitle" }}<p class="display-2 text-uppercase mb-0">{{ . | html }}</p>{{ end }}
-        <div class="pt-3 lead">
-          {{ if eq .Page.File.Ext "md" }}
-              {{ .Inner | markdownify }}
-          {{ else }}
-              {{ .Inner | htmlUnescape | safeHTML }}
-          {{ end }}
-        </div>
-      </div>
-    </div>
-  </div>
-  {{ with .Get "byline" | default "" -}}
-    <div class="byline">{{ . }}</div>
-  {{- end }}
+<section id="{{ $blockID }}" class="row td-cover-block td-cover-block--height-{{ $height -}}{{ if not .Site.Params.ui.navbar_translucent_over_cover_disable }} js-td-cover  {{- end }} td-overlay td-overlay--dark -bg-{{ $col_id }}">
+<div class="col-12">
+<div class="container td-overlay__inner">
+<div class="text-center">
+{{ with .Get "title" -}}
+{{ $title := . -}}
+<h1 class="display-1 mt-0 mt-md-5 pb-4">{{ with $logo_image }}{{ $logo_image_resized := (.Fit (printf "70x70 %s" $logo_anchor)) }}<img class="td-cover-logo" src="{{- $logo_image_resized.RelPermalink -}}" alt="{{- $title }} Logo">
+{{ end }}
+{{/* Do **not** remove this comment! It ends above html block! See https://spec.commonmark.org/0.30/#html-blocks, 7. */}}
+{{ . -}}</h1>
+{{ end -}}
+{{ with .Get "subtitle" -}}
+<div class="display-2 text-uppercase mb-0">
+{{/* Do **not** remove this comment! It ends above html block! See https://spec.commonmark.org/0.30/#html-blocks, 7. */}}
+{{ . -}}</div>
+{{ end -}}
+<div class="pt-3 lead">
+{{/* Do **not** remove this comment! It ends above html block! See https://spec.commonmark.org/0.30/#html-blocks, 7. */}}            
+{{ .Inner -}}
+</div>
+</div>
+</div>
+</div>
+{{ with .Get "byline" -}}
+<div class="byline">
+<small>
+{{/* Do **not** remove this comment! It ends above html block! See https://spec.commonmark.org/0.30/#html-blocks, 7. */}}  
+{{ . -}}
+</small>
+</div>
+{{ end }}
 </section>
 {{/**/ -}}
diff --git a/userguide/content/en/docs/adding-content/shortcodes/index.md b/userguide/content/en/docs/adding-content/shortcodes/index.md
@@ -36,8 +36,8 @@ color
 
 The **blocks/cover** shortcode creates a landing page type of block that fills the top of the page.
 
-```html
-{{</* blocks/cover title="Welcome!" image_anchor="center" height="full" color="primary" */>}}
+```go-html-template
+{{</* blocks/cover title="Welcome!" subtitle="Explore our site!" byline="Image attribution" image_anchor="center" height="full" color="primary" */>}}
 <div class="mx-auto">
 	<a class="btn btn-lg btn-primary me-3 mb-4" href="{{</* relref "/docs" */>}}">
 		Learn More <i class="fa-solid fa-circle-right ms-2"></i>
@@ -53,18 +53,19 @@ The **blocks/cover** shortcode creates a landing page type of block that fills t
 {{</* /blocks/cover */>}}
 ```
 
-Note that the relevant shortcode parameters above will have sensible defaults, but is included here for completeness.
+Note that the relevant shortcode parameters will have sensible defaults, but are included above for completeness.
 
-| Parameter        | Default    | Description  |
-| ---------------- |------------| ------------|
-| title | | The main display title for the block. |
-| image_anchor | |
-| height | | See above.
-| color | | See above.
-| byline | Byline text on featured image. |
+| Parameter    | Default    | Description                           |
+| ------------ |----------- | ------------------------------------- |
+| title        | n/a        | The main display title for the block. |
+| subtitle     | n/a        | The subtitle for the block.           |
+| image_anchor | `smart`    | Crop box placement for images, see also [`anchor`](https://gohugo.io/content-management/image-processing/#anchor) |                                    |
+| height       | `max`      | [See above](#shortcode-blocks).       |
+| color        | .Ordinal   | [See above](#shortcode-blocks).       |
+| byline       | n/a        | Byline text on featured image.        |
 
 
-To set the background image, place an image with the word "background" in the name in the page's [Page Bundle](/docs/adding-content/content/#page-bundles). For example, in our the example site the background image in the home page's cover block is [`featured-background.jpg`](https://github.com/google/docsy-example/tree/main/content/en), in the same directory.
+To set the background image, place an image with the word `background` as part of the file name in the page's [Page Bundle](/docs/adding-content/content/#page-bundles). For example, in our the example site the background image in the home page's cover block is [`featured-background.jpg`](https://github.com/google/docsy-example/tree/master/content/en), in the same directory.
 
 {{% alert title="Tip" %}}
 If you also include the word **featured** in the image name, e.g. `my-featured-background.jpg`, it will also be used as the Twitter Card image when shared.