Improve featured image (#17)

WARNING: UPGRADE HUGO TO VERSION 0.54.0 OR LATER

* post_thumbnail -> post_featured
* Add url, alt, caption and credit params for featured
* Add previewOnly param
* Add styles for featured
* Add fallback for thumbnail.*
* Add "Featured Images" page
* Show caption & credit on single pages only
* Update README: add featured image guide
* Bump Hugo min version because `reflect.IsMap` [0.38 -> 0.54.0]

README.md

@@ -32,7 +32,7 @@
     - [Post Meta](#post-meta)
     - [Related Content](#related-content)
     - [Share Buttons](#share-buttons)
-    - [Thumbnail Image](#thumbnail-image)
+    - [Featured Image](#featured-image)
     - [Footer Social Icons](#footer-social-icons)
     - [Web App Manifest](#web-app-manifest)
 - [Contributing](#contributing)
@@ -154,6 +154,9 @@ googleAnalytics = "" # Enable Google Analytics by entering your tracking id
   mathjaxConfig = "TeX-AMS-MML_HTMLorMML" # Specify MathJax config. Optional
   hideNoPostsWarning = false # Don't show no posts empty state warning in main page, if true
 
+[Params.Featured]
+  previewOnly = false # Show only preview featured image
+
 [Params.Social]
   email = "example@example.com"
   facebook = "username"
@@ -305,11 +308,34 @@ To display share buttons, set up `[Params.Share]` specific parameters in your si
 
 Available share buttons: Facebook, Twitter, Reddit, Telegram, LinkedIn, VK, Pocket, Pinterest
 
-#### Thumbnail Image
+#### Featured Image
 
-You can add thumbnail image to your content page. Just put `thumbnail.*` image file in
+There are two main different ways to add a featured image for a page.
+
+**Option 1.** Put `featured.*` or `thumbnail.*` image file in the
 [page bundle](https://gohugo.io/content-management/page-bundles/).
 
+**Option 2.** Put any image in the page bundle & specify `featured` param in the page's front matter.
+
+You may put any image in the page bundle and specify `featured` param in the page's front matter:
+
+```yaml
+featured: image.jpg
+```
+
+Or you can add some additional params like `alt`, `caption`, `credit` and `previewOnly`:
+
+```yaml
+featured:
+  url: image.jpg
+  alt: A scale model of the Eiffel tower standing on a map
+  caption: Eiffel tower model
+  credit: Unknown author
+  previewOnly: false
+```
+
+**Note**: `caption` and `credit` appear only on single pages, not summaries.
+
 #### Footer Social Icons
 
 With Binario, you have the option to display social icons in the footer. To display them, set up `[Params.Social]`

exampleSite/content/post/featured-images/index.md

@@ -0,0 +1,72 @@
+---
+title: Featured Images
+description: "In this page, we will explain what featured images are and show you some examples how to add a featured \
+image for a page."
+date: 2019-09-12
+---
+
+Featured image is the image that appears on summaries at the list pages and the top of content pages. Every content page
+in this theme can have a featured image.
+
+<!--more-->
+
+## How to add a featured image
+
+Content pages in Hugo can have their images or any other files stored under the same directory of the page itself.
+In Hugo's terms, it's called **page bundle** and allows us to keep all assets together with a page content file.
+
+This theme uses page bundles for featured images. There are two main different ways to add a featured image.
+
+### Option 1. Put `featured.*` or `thumbnail.*` image in the page bundle
+
+This theme considers `featured` or `thumbnail` image in any popular graphic format in the root of the page bundle as
+a featured image.
+
+Directory structure of this page:
+
+```
+content
+└── post
+    └── featured-images // single page folder (page bundle)
+        ├── featured.png // featured image
+        └── index.md // page content file
+```
+
+### Option 2. Put any image in the page bundle & specify `featured` param
+
+You may put any image in the page bundle and specify `featured` param in the page's front matter:
+
+```yaml
+featured: image.jpg
+```
+
+- `featured` [`String`]: relative path of the image
+
+Or you can add some additional params like `alt`, `caption`, `credit` and `previewOnly`:
+
+```yaml
+featured:
+  url: image.jpg
+  alt: A scale model of the Eiffel tower standing on a map
+  caption: Eiffel tower model
+  credit: Unknown author
+  previewOnly: false
+```
+
+- `featured` [`Map`]:
+  - `url` [`String`]: relative path of the image
+  - `alt` [`String`]: alternate text for the image
+  - `caption` [`String`]: image caption
+  - `credit` [`String`]: image credit
+  - `previewOnly` [`Boolean`]: show only preview image
+
+## FAQ
+
+**Q**: _What will happen if I specify `alt`, `caption`, `credit` params, but miss `url`? Featured image will be shown or
+not?_\
+**A**: In that case, featured image would appear only if the page bundle contains `featured.*` or `thumbnail.*` image.
+Otherwise, you'll get nothing.
+
+**Q**: _Is featured image path case sensitive or insensitive? Featured.png and featured.png are different image relative
+paths for Hugo?_\
+**A**: The image matching is case-insensitive. In that case, Featured.png and featured.png are identical for Hugo.

layouts/_default/single.html

@@ -2,7 +2,7 @@
 	<main class="main">
 		<div class="single block">
 			<article class="post">
-				{{- partial "post_thumbnail.html" (dict "page" .) }}
+				{{- partial "post_featured.html" (dict "page" . "IsSingle" true) }}
 				{{- partial "post_meta.html" (dict "dot" . "class" "mb") }}
 				<h1 class="post__title">{{ .Title }}</h1>
 				{{- partial "post_toc.html" . }}

layouts/_default/summary.html

@@ -1,5 +1,5 @@
 <article class="post card__box block">
-	{{- partial "post_thumbnail.html" (dict "page" . "link" .RelPermalink) }}
+	{{- partial "post_featured.html" (dict "page" . "link" .RelPermalink) }}
 	<h1 class="post__title title-excerpt"><a class="post__title-link" href="{{ .RelPermalink }}">{{ .Title }}</a></h1>
 	{{- with .Summary }}
 	<div class="post__content">{{ . }}</div>

layouts/partials/post_featured.html

@@ -0,0 +1,41 @@
+{{- with .page.Resources.ByType "image" }}
+	{{- $link := $.link -}}
+	{{- $IsSingle := $.IsSingle -}}
+	{{- $match := $.page.Params.featured -}}
+	{{- $featuredMap := "" -}}
+
+	{{- $IsMap := reflect.IsMap $match -}}
+	{{- if $IsMap }}
+		{{- $featuredMap = $match -}}
+		{{- $match = $match.url -}}
+	{{- end }}
+
+	{{- $featured := .GetMatch ($match | default "{featured.*,thumbnail.*}") -}}
+	{{ if and $featured (not (and $IsSingle ($.page.Param "featured.previewOnly"))) }}
+		<figure class="post__featured featured">
+			{{- with $link }}<a class="featured__link" href="{{ . }}">{{ end }}
+				<img class="featured__img" src="{{ $featured.RelPermalink }}" alt="
+					{{- with $featuredMap -}}
+						{{- .alt | default $featured.Title -}}
+					{{- else -}}
+						{{- $featured.Title -}}
+					{{- end -}}
+				"/>
+			{{- with $link }}</a>{{ end }}
+			{{- with $IsSingle }}
+				{{- with $featuredMap }}
+					{{- if or .caption .credit }}
+					<figcaption class="featured__figcaption">
+						{{- with .caption }}
+						<div class="featured__caption">{{ . | markdownify }}</div>
+						{{- end }}
+						{{- with .credit }}
+						<cite class="featured__credit">{{ . | markdownify }}</cite>
+						{{- end }}
+					</figcaption>
+					{{- end }}
+				{{- end }}
+			{{- end }}
+		</figure>
+	{{- end }}
+{{- end }}

layouts/partials/post_thumbnail.html

@@ -1,13 +0,0 @@
-{{- $img := (.page.Resources.ByType "image").GetMatch "thumbnail.*" }}
-{{- $link := .link }}
-{{- with $img }}
-	<figure class="post__thumbnail thumbnail">
-		{{- with $link }}
-		<a class="thumbnail__link" href="{{ . }}">
-			<img class="thumbnail__img" src="{{ $img.RelPermalink }}" alt="{{ $img.Title }}">
-		</a>
-		{{- else }}
-			<img class="thumbnail__img" src="{{ $img.RelPermalink }}" alt="{{ $img.Title }}">
-		{{- end }}
-	</figure>
-{{- end }}

static/css/main.css

@@ -699,8 +699,28 @@ button:not(:-moz-focusring):focus > .main-nav__btn-box {
 	font-size: 1.25rem;
 }
 
-.post__thumbnail {
+.post__featured {
+	width: 100%;
 	min-height: 1px; /* Workaround for IE11 flexbox img height issue https://github.com/philipwalton/flexbugs/issues/75 */
+	text-align: center;
+	background-color: #1f1f1f;
+}
+
+.featured__figcaption {
+	width: 100%;
+	padding: 1rem;
+	text-align: left;
+	background-color: #111;
+}
+
+.featured__credit::before {
+	content: "© ";
+}
+
+.featured__credit {
+	font-size: .875rem;
+	font-style: normal;
+	color: #888;
 }
 
 .post__content {

theme.toml

@@ -5,7 +5,7 @@ description = "Responsive card-based & code-light Hugo theme"
 homepage = "https://github.com/vimux/binario/"
 tags = ["blog", "dark", "disqus", "google analytics", "responsive"]
 features = []
-min_version = "0.38"
+min_version = "0.54.0"
 
 [author]
   name = "Vimux"