Add Featured Image section (#419)

Add Featured Image section

Co-authored-by: igor-baiborodine <igor-baiborodine@users.noreply.github.com>

1 files changed, 172 insertions, 154 deletions

diff --git a/README.md b/README.md
index cbd57b3..67bae67 100644
--- a/README.md
+++ b/README.md
@@ -38,6 +38,8 @@ Please use the following guidelines if you want to start a discussion:
   - [Other Tutorials](#other-tutorials)
 - [Features](#features)
   - [Default Post Types](#default-post-types)
+    - [Single Page](#single-page)
+    - [Page Bundle](#page-bundle)
   - [Top Navigation Bar](#top-navigation-bar)
   - [Algolia Search](#algolia-search)
     - [Initial Setup](#initial-setup)
@@ -54,6 +56,13 @@ Please use the following guidelines if you want to start a discussion:
     - [No Summary Split](#no-summary-split)
   - [Table of Contents (TOC)](#table-of-contents-toc)
   - [Series Taxonomy](#series-taxonomy)
+  - [External Images](#external-images)
+  - [Image Modal Zoom](#image-modal-zoom)
+  - [Featured Image](#featured-image)
+  - [Automatic Image Resizing](#automatic-image-resizing)
+  - [Video](#video)
+    - [PeerTube Configuration](#peertube-configuration)
+  - [Audio](#audio)
   - [Google Analytics](#google-analytics)
   - [Comments](#comments)
     - [Commento](#commento)
@@ -62,14 +71,8 @@ Please use the following guidelines if you want to start a discussion:
     - [Utterances](#utterances)
   - [Archive Page](#archive-page)
   - [Responsive Design](#responsive-design)
-  - [Automatic Image Resizing](#automatic-image-resizing)
-  - [Image Modal Zoom](#image-modal-zoom)
-  - [External Images](#external-images)
   - [MathJAX Markup](#mathjax-markup)
   - [Disabled Javascript Support](#disabled-javascript-support)
-  - [Video](#video)
-    - [PeerTube Configuration](#peertube-configuration)
-  - [Audio](#audio)
   - [Raw HTML](#raw-html)
 - [Customizations](#customizations)
   - [Favicons](#favicons)
@@ -183,20 +186,30 @@ hugo server
 ## Features
 
 ### Default Post Types
-Bilberry theme comes with a set of predefined post types, namely `article`, `audio`, `code`, `gallery`, `link`, `page`, `quote`, `status`, and `video` where the `article` type is the default one.
 
-To create a new content, use the `hugo new` command. Content can be created in two ways: a single page or a [page bundle](https://gohugo.io/content-management/page-bundles/).
+Bilberry theme comes with a set of predefined post types, namely `article`, `audio`, `code`, `gallery`, `link`, `page`
+, `quote`, `status`, and `video` where the `article` type is the default one.
 
+To create a new content, use the `hugo new` command. Content can be created in two ways: a single page or
+a [page bundle](https://gohugo.io/content-management/page-bundles/).
+
+#### Single Page
 To create new content as a single page, you can use the following command:
+
 ```shell
 hugo new <content-type>/my-single-page-content.md
 ```
+
+#### Page Bundle
 Or, new page bundle content can be created as follows:
+
 ```shell
 hugo new <content-type>/my-page-bundle-content/index.md
 ```
 
-For example, you can create a new article as a single page and a new gallery as a page bundle using the following commands respectively:
+For example, you can create a new article as a single page and a new gallery as a page bundle using the following
+commands respectively:
+
 ```shell
 hugo new article/my-single-page-article.md
 hugo new gallery/my-page-bundle-gallery/index.md
@@ -210,13 +223,11 @@ The `page` content can be a static page, such as an **About** page, or a link to
 
 The `link` post type always links to an external site and can be used with or without a background image.
 
-
 ### Top Navigation Bar
 If you want to permanently display the top navigation bar with the search text field and `page` items, set the `permanentTopNav` parameter to `true` in the `config.toml` file.
 
 Please note that the top navigation bar is minimized by default on mobile devices.
 
-
 ### Algolia Search
 Bilberry theme includes built-in content search via [Algolia SAAS](https://www.algolia.com/). 
 You can see this in action on the [demo site](https://lednerb.github.io/bilberry-hugo-theme) by clicking on "hamburger" and typing something in the search text field, such as "support."
@@ -262,12 +273,10 @@ Execute the `hugo` command in the site's root directory to generate the `index.j
 Also, you can read this [write-up](https://www.kiroule.com/article/automate-data-upload-to-algolia-index-revisited/) on how to automate
 data upload to Algolia index if you host your Bilberry theme-based website on Netlify, or this [write-up](https://www.kiroule.com/article/automate-data-upload-to-algolia-index-with-github-actions/) using GitHub Actions.
 
-
 ### Keyboard Shortcuts
 Type `s` to open the navigation bar and set focus to the search input field. 
 To remove focus, press the `Esc` key.
 
-
 ### Reposted Article/Duplicated Content
 If you need to repost an article from another website or duplicate content on your site, you should link it to the original URL so it's correctly processed by SEO. 
 To do so, define the `original_url` front matter variable in your post, for example:
@@ -275,14 +284,12 @@ To do so, define the `original_url` front matter variable in your post, for exam
 original_url: "https://example.org/path/to/content"
 ```
 
-
 ### Calculated Reading Time
 To override the automatically calculated reading time for a post, you can use the `readingTime` front matter variable, for example:
 ```
 readingTime: 7 # integer value in  minutes
 ```
 
-
 ### Summary Splits
 There are three options for how Hugo can generate summaries of content which will be used as a short version in summary views, such as a home page and tags or categories pages.
 
@@ -301,7 +308,6 @@ This summary will also be followed by the _Continue reading_ link.
 #### No Summary Split
 If you want to display the entire article without the _Continue Reading_ link, set the `noSummary` variable to `true` in your content file.
 
-
 ### Table of Contents (TOC)
 To enable the automatic creation of a table of contents (TOC), set the `toc` front matter variable to `true` in your article. 
 If the article's markdown contains appropriate headings, Hugo will generate a table of content at the beginning of the article. 
@@ -315,7 +321,6 @@ Also, if you want to display a TOC at a specific point in your article, set the
 {{< toc >}}
 ```
 
-
 ### Series Taxonomy 
 In case you want to group some articles as a series, you have to add the `series` front matter variable to each article and set its value to the name of the series, for example, `series: "My New Super Series"`.
 
@@ -324,137 +329,11 @@ The page at `<site-base-url>/series/` will list all the series. To list all arti
 {{< series "My New Super Series" >}}
 ```
 
-### Google Analytics
-Bilberry theme comes with built-in support for both v3 and v4 of [Google Analytics](https://analytics.google.com/analytics/web/). 
-You should set the value of the `googleAnalytics` property in the `config.toml` file to enable it.
-
-Such value for Universal Analytics v3 is prefixed with the `UA` letters. 
-So, suppose you migrate your existing website to the Bilberry theme, and your website is already tracked in Universal Analytics, given that the corresponding property was created before October 14, 2020. 
-In that case, you should continue using the v3 value in the `config.toml` file. 
-But given that Universal Analytics will no longer process new data in standard properties beginning July 1, 2023, you will have to create a Google Analytics v4 property linked to your v3 property.
-
-If you created your property after October 14, 2020, you're likely using a Google Analytics v4 property already, and the value for such property is prefixed with the `G` letter. 
-In that case, you should use the v4 value in the `config.toml` file.
-
-### Comments
-To allow readers to comment under your articles, you can use either [Commento](https://commento.io/), [Disqus](https://disqus.com/), [Giscus](https://giscus.app/), or [Utterances](https://utteranc.es/).
-
-#### Commento
-Follow this [guide](https://docs.commento.io/installation/cloud-service/) if you want to use Commento Cloud Service which is not free of cost.
-
-In case you want to use Self-hosting Commento, follow these [instructions](https://docs.commento.io/installation/self-hosting/).
-
-Then uncomment the `commentoJsURL` parameter in the `config.toml` file:
-```toml
-#[...]
-[params]
-    #[...]
-
-    # Commento
-    commentoJsURL = "http://localhost:8080/js/commento.js"
-```
-
-#### Disqus
-To allow readers to leave comments under your articles, sign up for free on [Disqus](https://disqus.com) website. 
-Then create a new site and set the `disqusShortname` parameter to your site's short name in the `config.toml` file:
-```toml
-#[...]
-[params]
-    #[...]
-
-    # Disqus
-    disqusShortname = "lednerb"
-```
-
-You can manage and moderate the comments either on your website or using the Disqus management panel.
-
-#### Giscus
-Follow instructions on [Giscus](https://giscus.app/) website. 
-Once you complete the prerequisites for your GitHub repository and select a discussion category, values for `giscusRepositoryId` and `giscusCategoryId` will be automatically generated. 
-Then, in the `config.toml` file, set the `giscus` parameter to `true` and the properties mentioned above, respectively: 
-```toml
-#[...]
-[params]
-    #[...]
-
-    # Giscus
-    giscus              = true
-    giscusJsUrl         = "https://giscus.app/client.js"
-    giscusRepository    = "Lednerb/bilberry-hugo-theme"
-    giscusRepositoryId  = "R_kgDOGX153A" # generated by Giscus website
-    giscusMapping       = "pathname"
-    giscusCategory      = "General"
-    giscusCategoryId    = "DIC_kwDOGX153M4B_2Vz" # generated by Giscus website
-    giscusTheme         = "light"
-    giscusReactions     = "1"
-    giscusEmitMetadata  = "0"
-    giscusLanguage      = "en"
-    giscusCrossOrigin   = "anonymous"
-```
-
-#### Utterances
-Follow instructions on [Utterances](https://utteranc.es/) website. 
-Once you complete the prerequisites for your GitHub repository, set the `utterances` parameter to `true` in the `config.toml` file:
-```toml
-#[...]
-[params]
-    #[...]
-
-    # Utterances
-    utterances            = true
-    utterancesJsUrl       = "https://utteranc.es/client.js"
-    utterancesRepository  = "Lednerb/bilberry-hugo-theme"
-    utterancesIssueTerm   = "pathname"
-    utterancesLabel       = "Comment"
-    utterancesTheme       = "github-light"
-    utterancesCrossOrigin = "anonymous"
-```
-
-### Archive Page
-
-The archive page will be available at `<site-base-url>/archive/` as soon as you copy
-the `themes/bilberry-hugo-theme/exampleSite/content/archive.md` file to `content` directory of your
-site. By default, the published content is grouped by year. To group the content by year and month,
-set the `archiveDateGrouping` parameter to the `2006-01` value.
-
-To display the archive link in the footer, set the `showArchive` parameter to `true`.
-
-To add the archive link to the top navigation bar, create a new page with the following command:
-
-```shell
-hugo new page/archive.md
-```
-
-Then, in the newly created `content/page/archive.md` file, set the `link` front matter variable to
-the `/archive/` value and completely remove the `target` variable.
-
-### Responsive Design
-Bilberry theme is optimized to look good on all devices, namely desktops, tablets and smartphones.
-
-### Automatic Image Resizing
-Bilberry theme includes built-in automatic cropping and resizing only for **featured** and **gallery** images, activated by default.
-However, if you want to disable it, set the `resizeImages` parameter to `false` in the `config.toml` file.
-Also, this feature can be disabled at the post level by setting the `resizeImages` front matter variable to `false`.
-
-For a featured image to be cropped and resized, it should be named `featuredImage.*` where the `*` is the image file extension, e.g., `jpg`, `png`, etc.
-Also, it should be placed within the page bundle in question, for example:
-```shell
-content
-└── article
-    └── my-post-with-featured-image
-        ├── featuredImage.png
-        └── index.md
-```
-**NOTE**: a featured image defined via the `featuredImage` front matter parameter will **NOT** be cropped and resized.
-
-### Image Modal Zoom
-When you include an image that is larger than the content area, the image becomes interactive and a larger version can be opened in a lightbox.
-
 ### External Images
 
 If you would like to use external images, such as those stored on another server or in the cloud, as
 a featured image for your article or in the `gallery` post type, you can use them by setting the
-appropriate front matter variables with the full-path URL values:
+appropriate front matter variables with the absolute URL values:
 
 ```markdown
 # /content/article/my-external-featured-image-post.md
@@ -472,21 +351,44 @@ gallery: [
 ]
 ```
 
-### MathJAX Markup
-To enable the [MathJAX](https://www.mathjax.org) markup support, set the `enable_mathjax` parameter to `true` in the `config.toml` file.
+### Image Modal Zoom
 
+When you include an image that is larger than the content area, the image becomes interactive and a larger version can
+be opened in a lightbox.
 
-### Disabled Javascript Support
-Although this theme has a lot of features that only work with enabled JavaScript, it also fully supports disabled JavaScript. 
-Disabled Javascript will not break any styling or essential functionalities of your website.
+### Featured Image
 
-You can test the behavior of the [demo site](https://lednerb.github.io/bilberry-hugo-theme) by disabling JavaScript in your browser.
+There are two options for adding a featured image to a post. The first approach is to use a [single-page](#single-page)
+post with the `featuredImage` front matter variable, where the value for this variable should be either the path
+relative to the base URL or an absolute URL.
+
+Alternatively, when using a [page-bundle](#page-bundle) post, the intended featured image should be
+named `featuredImage.*` where the `*` is the image file extension, e.g., `jpg`, `png`, etc. Also, it should be placed
+within the page bundle in question, for example:
+
+```shell
+content
+└── article
+    └── my-post-with-featured-image
+        ├── featuredImage.png
+        └── index.md
+```
 
+### Automatic Image Resizing
+
+Bilberry theme includes built-in automatic cropping and resizing only for **featured** and **gallery** images, activated
+by default. However, if you want to disable it, set the `resizeImages` parameter to `false` in the `config.toml` file.
+Also, this feature can be disabled at the post level by setting the `resizeImages` front matter variable to `false`.
+
+For a featured image to be cropped and resized, it should be named `featuredImage.*` and placed within the page bundle
+folder.
+
+**NOTE**: a featured image defined via the `featuredImage` front matter parameter will **NOT** be cropped and resized.
 
 ### Video
 The following video hosting providers are supported: [YouTube](https://www.youtube.com/), [Vimeo](https://vimeo.com/),  [Prezi](https://prezi.com/), [Bilibili](https://www.bilibili.com), and [PeerTube](https://joinpeertube.org).
-Videos in the `MP4` format, either stored externally or within the site's `static` folder, are also supported. 
-There are two options to display video embeds. 
+Videos in the `MP4` format, either stored externally or within the site's `static` folder, are also supported.
+There are two options to display video embeds.
 
 The first option is to use a post of the `video` type. Use the following command to create your video post:
 ```bash
@@ -542,8 +444,8 @@ Instead, copy in the entire watch URL, and it'll be transformed into the correct
 There is an [instance finder](https://joinpeertube.org/instances#instances-list) if you want to start hosting your videos on PeerTube but don't know which instance to join.
 
 ### Audio
-The following audio streaming providers are supported: [Mixcloud](https://www.mixcloud.com/), [SoundCloud](https://soundcloud.com/), [Spotify](https://www.spotify.com/), and [TuneIn](https://tunein.com/). 
-Audio files in the `Ogg`, `MP3`, or `WAV` formats, either stored externally or within the site's `static` folder, are also supported. 
+The following audio streaming providers are supported: [Mixcloud](https://www.mixcloud.com/), [SoundCloud](https://soundcloud.com/), [Spotify](https://www.spotify.com/), and [TuneIn](https://tunein.com/).
+Audio files in the `Ogg`, `MP3`, or `WAV` formats, either stored externally or within the site's `static` folder, are also supported.
 There are two options to display audio embeds.
 
 The first option is to use a post of the `audio` type. Use the following command to create your audio post:
@@ -586,6 +488,122 @@ The second option is to use the `audio` shortcode within markdown content in a p
 {{< audio type="audiofile" url="/<audio-file-name>.mp3" >}}
 ```
 
+### Google Analytics
+Bilberry theme comes with built-in support for both v3 and v4 of [Google Analytics](https://analytics.google.com/analytics/web/). 
+You should set the value of the `googleAnalytics` property in the `config.toml` file to enable it.
+
+Such value for Universal Analytics v3 is prefixed with the `UA` letters. 
+So, suppose you migrate your existing website to the Bilberry theme, and your website is already tracked in Universal Analytics, given that the corresponding property was created before October 14, 2020. 
+In that case, you should continue using the v3 value in the `config.toml` file. 
+But given that Universal Analytics will no longer process new data in standard properties beginning July 1, 2023, you will have to create a Google Analytics v4 property linked to your v3 property.
+
+If you created your property after October 14, 2020, you're likely using a Google Analytics v4 property already, and the value for such property is prefixed with the `G` letter. 
+In that case, you should use the v4 value in the `config.toml` file.
+
+### Comments
+To allow readers to comment under your articles, you can use either [Commento](https://commento.io/), [Disqus](https://disqus.com/), [Giscus](https://giscus.app/), or [Utterances](https://utteranc.es/).
+
+#### Commento
+Follow this [guide](https://docs.commento.io/installation/cloud-service/) if you want to use Commento Cloud Service which is not free of cost.
+
+In case you want to use Self-hosting Commento, follow these [instructions](https://docs.commento.io/installation/self-hosting/).
+
+Then uncomment the `commentoJsURL` parameter in the `config.toml` file:
+```toml
+#[...]
+[params]
+    #[...]
+
+    # Commento
+    commentoJsURL = "http://localhost:8080/js/commento.js"
+```
+
+#### Disqus
+To allow readers to leave comments under your articles, sign up for free on [Disqus](https://disqus.com) website. 
+Then create a new site and set the `disqusShortname` parameter to your site's short name in the `config.toml` file:
+```toml
+#[...]
+[params]
+    #[...]
+
+    # Disqus
+    disqusShortname = "lednerb"
+```
+
+You can manage and moderate the comments either on your website or using the Disqus management panel.
+
+#### Giscus
+Follow instructions on [Giscus](https://giscus.app/) website. 
+Once you complete the prerequisites for your GitHub repository and select a discussion category, values for `giscusRepositoryId` and `giscusCategoryId` will be automatically generated. 
+Then, in the `config.toml` file, set the `giscus` parameter to `true` and the properties mentioned above, respectively: 
+```toml
+#[...]
+[params]
+    #[...]
+
+    # Giscus
+    giscus              = true
+    giscusJsUrl         = "https://giscus.app/client.js"
+    giscusRepository    = "Lednerb/bilberry-hugo-theme"
+    giscusRepositoryId  = "R_kgDOGX153A" # generated by Giscus website
+    giscusMapping       = "pathname"
+    giscusCategory      = "General"
+    giscusCategoryId    = "DIC_kwDOGX153M4B_2Vz" # generated by Giscus website
+    giscusTheme         = "light"
+    giscusReactions     = "1"
+    giscusEmitMetadata  = "0"
+    giscusLanguage      = "en"
+    giscusCrossOrigin   = "anonymous"
+```
+
+#### Utterances
+Follow instructions on [Utterances](https://utteranc.es/) website. 
+Once you complete the prerequisites for your GitHub repository, set the `utterances` parameter to `true` in the `config.toml` file:
+```toml
+#[...]
+[params]
+    #[...]
+
+    # Utterances
+    utterances            = true
+    utterancesJsUrl       = "https://utteranc.es/client.js"
+    utterancesRepository  = "Lednerb/bilberry-hugo-theme"
+    utterancesIssueTerm   = "pathname"
+    utterancesLabel       = "Comment"
+    utterancesTheme       = "github-light"
+    utterancesCrossOrigin = "anonymous"
+```
+
+### Archive Page
+
+The archive page will be available at `<site-base-url>/archive/` as soon as you copy
+the `themes/bilberry-hugo-theme/exampleSite/content/archive.md` file to `content` directory of your
+site. By default, the published content is grouped by year. To group the content by year and month,
+set the `archiveDateGrouping` parameter to the `2006-01` value.
+
+To display the archive link in the footer, set the `showArchive` parameter to `true`.
+
+To add the archive link to the top navigation bar, create a new page with the following command:
+
+```shell
+hugo new page/archive.md
+```
+
+Then, in the newly created `content/page/archive.md` file, set the `link` front matter variable to
+the `/archive/` value and completely remove the `target` variable.
+
+### Responsive Design
+Bilberry theme is optimized to look good on all devices, namely desktops, tablets and smartphones.
+
+### MathJAX Markup
+To enable the [MathJAX](https://www.mathjax.org) markup support, set the `enable_mathjax` parameter to `true` in the `config.toml` file.
+
+### Disabled Javascript Support
+Although this theme has a lot of features that only work with enabled JavaScript, it also fully supports disabled JavaScript. 
+Disabled Javascript will not break any styling or essential functionalities of your website.
+
+You can test the behavior of the [demo site](https://lednerb.github.io/bilberry-hugo-theme) by disabling JavaScript in your browser.
+
 ### Raw HTML
 If you want to include raw HTML in your markdown content, set the `unsafe` setting in the `config.toml` file to `true`:
 ```toml