diff --git a/layouts/shortcodes/blocks/cover.html b/layouts/shortcodes/blocks/cover.html
index a055c399f9..9f53fb621c 100644
--- 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)) -}}
@@ -31,20 +36,32 @@
- {{ with .Get "title" }}
{{ $title := . }}{{ with $logo_image }}{{ $logo_image_resized := (.Fit (printf "70x70 %s" $logo_anchor)) }}{{ end }}{{ $title | html }}
{{ end }}
- {{ with .Get "subtitle" }}
{{ . | html }}
{{ end }}
-
- {{ if eq .Page.File.Ext "md" }}
- {{ .Inner | markdownify }}
- {{ else }}
- {{ .Inner | htmlUnescape | safeHTML }}
- {{ end }}
-
-
-
-
- {{ with .Get "byline" | default "" -}}
- {{ . }}
- {{- end }}
+{{ with .Get "title" -}}
+{{ $title := . -}}
+{{ with $logo_image }}{{ $logo_image_resized := (.Fit (printf "70x70 %s" $logo_anchor)) }}{{ end }}
+{{/* Do **not** remove this comment! It ends above html block! See https://spec.commonmark.org/0.30/#html-blocks, 7. */}}
+{{ . -}}
+{{ end -}}
+{{ with .Get "subtitle" -}}
+
+{{/* Do **not** remove this comment! It ends above html block! See https://spec.commonmark.org/0.30/#html-blocks, 7. */}}
+{{ . -}}
+{{ end -}}
+
+{{/* Do **not** remove this comment! It ends above html block! See https://spec.commonmark.org/0.30/#html-blocks, 7. */}}
+{{ .Inner -}}
+
+
+
+
+
+{{ with .Get "byline" -}}
+
+
+{{/* Do **not** remove this comment! It ends above html block! See https://spec.commonmark.org/0.30/#html-blocks, 7. */}}
+{{ . -}}
+
+
+{{ end }}
{{/**/ -}}
diff --git a/userguide/content/en/docs/adding-content/shortcodes/index.md b/userguide/content/en/docs/adding-content/shortcodes/index.md
index c98485f7a0..c02030d50b 100644
--- 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" */>}}
}}">
Learn More
@@ -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/master/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.