Skip to content

Commit

Permalink
shortcode 'blocks/cover': improvements
Browse files Browse the repository at this point in the history
- use Hugo's native support for processing HTML & markdown (#906)
- drop support for pre-Hugo-0.54.x behavior of {{% %}} #939
  • Loading branch information
deining committed Feb 15, 2023
1 parent 8ae1625 commit 5140c98
Show file tree
Hide file tree
Showing 2 changed files with 62 additions and 47 deletions.
86 changes: 50 additions & 36 deletions layouts/shortcodes/blocks/cover.html
Original file line number Diff line number Diff line change
@@ -1,16 +1,21 @@
{{ $_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" }}
{{ $byline := .Get "byline" | default "" }}
{{ with $promo_image }}
{{ $promo_image_big := (.Fill (printf "1920x1080 %s" $image_anchor)) }}
{{ $promo_image_small := (.Fill (printf "960x540 %s" $image_anchor)) }}
{{ $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 := "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)) -}}
<link rel="preload" as="image" href="{{ $promo_image_small.RelPermalink }}" media="(max-width: 1200px)">
<link rel="preload" as="image" href="{{ $promo_image_big.RelPermalink }}" media="(min-width: 1200px)">
<style>
Expand All @@ -24,27 +29,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="container td-overlay__inner">
<div class="row">
<div class="col-12">
<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>
</div>
{{ if $byline }}
<div class="byline">
<small>{{ $byline }}</small>
</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="container td-overlay__inner">
<div class="row">
<div class="col-12">
<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>
</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>
23 changes: 12 additions & 11 deletions userguide/content/en/docs/adding-content/shortcodes/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,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>
Expand All @@ -46,23 +46,24 @@ 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.

{{% alert title="Hugo Tip" %}}
> Using the bracket styled shortcode delimiter, `>}}`, tells Hugo that the inner content is HTML/plain text and needs no further processing. Changing the delimiter to `%}}` means Hugo will treat the content as Markdown. You can use both styles in your pages.
{{% /alert %}}


| 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.
Expand Down

0 comments on commit 5140c98

Please sign in to comment.