Rename Partial, Add Documentation

Renamed the partial to func/GetFeaturedImage.html.

Additionally added more documentation in the partial to explain how it
worked, and what values were returned.

layouts/partials/featured.html

@@ -1,10 +0,0 @@
-{{ $linkToCover := "" }}
-{{ if .Params.featured_image }}
-    {{ $linkToCover = .Params.featured_image }}
-{{ else }}
-    {{ $img := .Resources.GetMatch "**cover*.jpg" }}
-    {{ with $img }}
-        {{ $linkToCover = .Permalink }}
-    {{ end }}
-{{ end }}
-{{ return $linkToCover }}

layouts/partials/func/GetFeaturedImage.html

@@ -0,0 +1,35 @@
+{{/* 
+    GetFeaturedImage
+
+    This partial gets the url for featured image for a given page. 
+    
+    If a featured_image was set in the page's front matter, then that will be used.
+
+    If not set, this will search page resources to find an image that contains the word
+    "cover", and if found, returns the path to that resource.
+
+    If no featured_image was set, and there's no "cover" image in page resources, then
+    this partial returns an empty string (which evaluates to false).
+
+    @return Permalink to featured image, or an empty string if not found.
+
+*/}}
+
+{{/* Declare a new string variable, $linkToCover */}}
+{{ $linkToCover := "" }}
+
+{{/* Use the value from front matter if present */}}
+{{ if .Params.featured_image }}
+    {{ $linkToCover = .Params.featured_image }}
+
+{{/* Find the first image with 'cover' in the name in this page bundle. */}}
+{{ else }}
+    {{ $img := (.Resources.ByType "image").GetMatch "*cover*" }}
+    {{ with $img }}
+        {{ $linkToCover = .Permalink }}
+    {{ end }}
+{{ end }}
+
+{{/* return either a permalink, or an empty string. Note that partials can only have a single
+return statement, so this needs to be at the end of the partial (and not in the if block) */}}
+{{ return $linkToCover }}

layouts/partials/page-header.html

@@ -1,4 +1,4 @@
-{{ $featured_image := partial "featured.html" . }}
+{{ $featured_image := partial "func/GetFeaturedImage.html" . }}
 {{ if $featured_image }}
   {{/* Trimming the slash and adding absURL make sure the image works no matter where our site lives */}}
   {{ $featured_image := (trim $featured_image "/") | absURL }}

layouts/partials/summary-with-image.html

@@ -1,4 +1,4 @@
-{{ $featured_image := partial "featured.html" . }}
+{{ $featured_image := partial "func/GetFeaturedImage.html" . }}
 <article class="bb b--black-10">
   <div class="db pv4 ph3 ph0-l no-underline dark-gray">
     <div class="flex flex-column flex-row-ns">

layouts/post/summary-with-image.html

@@ -1,7 +1,7 @@
 <article class="bb b--black-10">
   <a class="db pv4 ph3 ph0-l no-underline dark-gray dim" href="{{ .Permalink }}">
     <div class="flex flex-column flex-row-ns">
-      {{ $featured_image := partial "featured.html" . }}
+      {{ $featured_image := partial "func/GetFeaturedImage.html" . }}
       {{ if $featured_image }}
         <div class="pr3-ns mb4 mb0-ns w-100 w-40-ns">
           <img src="{{ $featured_image }}" class="db" alt="image from {{ .Title }}">