v2: Introduce show_overlay_excerpt and document (#1436)

Make excerpts optional in header overlay

Some posts and some header images don't lend themselves well to
displaying the excerpt in the overlay. Make this optional by
introducting a new boolean variable:

`page.header.show_overlay_excerpt`

Set it to implicitly default to `true` so existing users are unaffected by
testing explicitly for "!= false".

This can be enabled globally for a site by changing the default to `false`
in the local _config.yml, or per page by specifying the value in front
matter.

Document show_overlay_excerpt variable

* Add show_overlay_excerpt variable to the Header Overlay field documentation table.

Close #1429

_includes/page__hero.html

@@ -42,7 +42,7 @@ <h1 class="page__title" itemprop="headline">
           {{ page.title | default: site.title | markdownify | remove: "<p>" | remove: "</p>" }}
         {% endif %}
       </h1>
-      {% if page.excerpt %}
+      {% if page.header.show_overlay_excerpt != false and page.excerpt %}
         <p class="page__lead">{{ page.excerpt | markdownify | remove: "<p>" | remove: "</p>" }}</p>
       {% endif %}
       {% if site.read_time and page.read_time %}

docs/_docs/10-layouts.md

@@ -339,13 +339,14 @@ header:
 
 To overlay text on top of a header image you have a few more options:
 
-| Name               | Description | Default |
-| ----               | ----------- | ------- |
-| **overlay_image**  | Header image you'd like to overlay. Same rules as `header.image` from above. | |
-| **overlay_filter** | Color/opacity to overlay on top of the header image eg: `0.5` or `rgba(255, 0, 0, 0.5)`. |
-| **excerpt**        | Auto-generated page excerpt is added to the overlay text or can be overridden. | |
-| **cta_label**      | Call to action button text label. | `more_label` in UI Text data file |
-| **cta_url**        | Call to action button URL. | |
+| Name                     | Description | Default |
+| ----                     | ----------- | ------- |
+| **overlay_image**        | Header image you'd like to overlay. Same rules as `header.image` from above. | |
+| **overlay_filter**       | Color/opacity to overlay on top of the header image eg: `0.5` or `rgba(255, 0, 0, 0.5)`. |
+| **show_overlay_excerpt** | Display excerpt in the overlay text | true |
+| **excerpt**              | Auto-generated page excerpt is added to the overlay text or can be overridden. | |
+| **cta_label**            | Call to action button text label. | `more_label` in UI Text data file |
+| **cta_url**              | Call to action button URL. | |
 
 With this YAML Front Matter: