Shortcode 'blocks/lead' improvements (#1398)

layouts/shortcodes/blocks/lead.html

@@ -1,16 +1,17 @@
-{{ $_hugo_config := `{ "version": 1 }` -}}
 {{ $col_id := .Get "color" | default .Ordinal -}}
 {{ $height := .Get "height" | default "auto" -}}
-{{/* Height can be one of: auto, min, med, max, full. */ -}}
-<a id="td-block-{{ .Ordinal }}" class="td-offset-anchor"></a>
+{{ with .Get "height" -}}
+  {{ if not ( or ( eq . "auto" ) ( eq . "min" ) ( eq . "med" ) ( eq . "max" ) ( eq . "full" ) ) -}}
+    {{ errorf "shortcode 'lead': parameter height is '%s', must be one of 'auto', 'min', 'med', 'max' or 'full'." . -}}
+  {{ end -}}
+{{ end -}}
+<div><a id="td-block-{{ .Ordinal }}" class="td-offset-anchor"></a></div>
 <section class="row td-box td-box--{{ $col_id }} position-relative td-box--height-{{ $height }}">
-	<div class="container text-center td-arrow-down">
-		<div class="h4 mb-0">
-			{{ if eq .Page.File.Ext "md" -}}
-				{{ .Inner | markdownify -}}
-			{{ else -}}
-				{{ .Inner | htmlUnescape | safeHTML -}}
-			{{ end -}}
-		</div>
-	</div>
+<div class="container text-center td-arrow-down">
+<div class="h4 mb-0">
+{{/* Do NOT remove this comment! It ends above HTML block. See https://spec.commonmark.org/0.30/#html-blocks, 7. */}}
+{{ .Inner }}
+</div>
+</div>
 </section>
+{{/**/ -}}

userguide/content/en/_index.html → userguide/content/en/_index.md

@@ -2,18 +2,19 @@
 title: Docsy
 ---
 
-{{< blocks/cover title="Welcome to Docsy!" image_anchor="top" height="full" >}}
-<div class="mx-auto">
-	<a class="btn btn-lg btn-primary me-3 mb-4" href="{{< relref "/about" >}}">
-		Learn More <i class="fa-solid fa-circle-right ms-2"></i>
-	</a>
-	<a class="btn btn-lg btn-secondary me-3 mb-4" href="https://github.com/google/docsy">
-		Download <i class="fa-brands fa-github ms-2 "></i>
-	</a>
-	<p class="lead mt-5">A Hugo theme for creating great technical documentation sites</p>
-	{{< blocks/link-down color="info" >}}
-</div>
-{{< /blocks/cover >}}
+{{% blocks/cover title="Welcome to Docsy!" image_anchor="top" height="full" %}}
+<a class="btn btn-lg btn-primary me-3 mb-4" href="{{% relref "/about" %}}">
+  Learn More <i class="fa-solid fa-circle-right ms-2"></i>
+</a>
+<a class="btn btn-lg btn-secondary me-3 mb-4" href="https://github.com/google/docsy">
+  Download <i class="fa-brands fa-github ms-2 "></i>
+</a>
+
+A Hugo theme for creating great technical documentation sites
+{.lead .mt-5}
+
+{{% blocks/link-down color="info" %}}
+{{% /blocks/cover %}}
 
 {{% blocks/lead color="primary" %}}
 Docsy is a theme for the Hugo static site generator that's specifically designed
@@ -26,7 +27,7 @@
 </a>
 {{% /blocks/lead %}}
 
-{{< blocks/section color="dark" type="features">}}
+{{% blocks/section color="dark" type="features"%}}
 {{% blocks/feature icon="fa-lightbulb" title="See Docsy in action!" url="/docs/examples/" %}}
 As well as our example site, there's a growing number of projects using Docsy for their doc sites.
 {{% /blocks/feature %}}
@@ -41,4 +42,4 @@
 Find out about new features and how our users are using Docsy.
 {{% /blocks/feature %}}
 
-{{< /blocks/section >}}
+{{% /blocks/section %}}

userguide/content/en/docs/adding-content/shortcodes/index.md

@@ -1,6 +1,6 @@
 ---
-title: "Docsy Shortcodes"
-linkTitle: "Docsy Shortcodes"
+title: Docsy Shortcodes
+linkTitle: Shortcodes
 date: 2017-01-05
 weight: 5
 description: >
@@ -13,6 +13,13 @@ resources:
 
 Rather than writing all your site pages from scratch, Hugo lets you define and use [shortcodes](https://gohugo.io/content-management/shortcodes/). These are reusable snippets of content that you can include in your pages, often using HTML to create effects that are difficult or impossible to do in simple Markdown. Shortcodes can also have parameters that let you, for example, add your own text to a fancy shortcode text box. As well as Hugo's [built-in shortcodes](https://gohugo.io/content-management/shortcodes/), Docsy provides some shortcodes of its own to help you build your pages.
 
+## Shortcode delimiters
+
+As illustrated below, using the bracket styled [shortcode delimiter][],
+`{{</*...*/>}}`, tells Hugo that the inner content is HTML/plain text and needs
+no further processing. By using the delimiter `{{%/*...*/%}}`, Hugo will treat
+the shortcode body as Markdown. You can use both styles in your pages.
+
 ## Shortcode blocks
 
 The theme comes with a set of custom  **Page Block** shortcodes that can be used to compose landing pages, about pages, and similar.
@@ -48,11 +55,6 @@ The **blocks/cover** shortcode creates a landing page type of block that fills t
 
 Note that the relevant shortcode parameters above will have sensible defaults, but is included here 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. |
@@ -82,10 +84,10 @@ Runs on **bare metal** in the **cloud**!
 {{%/* /blocks/lead */%}}
 ```
 
-| Parameter        | Default    | Description  |
-| ---------------- |------------| ------------|
-| height | | See above.
-| color | | See above.
+| Parameter | Default  | Description                               |
+| --------- |--------- | ----------------------------------------- |
+| height    | `auto`   | See [Shortcode blocks](#shortcode-blocks) |
+| color     | .Ordinal | See [Shortcode blocks](#shortcode-blocks) |
 
 ### blocks/section
 
@@ -157,7 +159,6 @@ The **alert** shortcode creates an alert block that can be used to display notic
 {{%/* alert title="Warning" color="warning" */%}}
 This is a warning.
 {{%/* /alert */%}}
-
 ```
 
 Renders to:
@@ -700,3 +701,5 @@ This text does not appear in the output if `buildCondition = "bar" is set in you
 ```
 
 If you are using this shortcode, note that when evaluating the conditions, substring matches are matches as well. That means, if you set `include-if="foobar"`, and `buildcondition = "foo"`, you have a match!
+
+[shortcode delimiter]: https://gohugo.io/content-management/shortcodes/#use-shortcodes