✨ Add menu icon support and flexible search link

CHANGELOG.md

@@ -8,6 +8,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ### Added
 
+- Support for icons in menus including support for links styled as an icon by itself or an icon with text
+- Search link can now be fully customised and positioned anywhere in the menu
 - Front matter support for specifying article thumbnails, covers and featured image details (including filename pattern, alt text and caption)
 - Support for SVG assets as article thumbnails, covers and featured images
 - Front matter keywords support on a per article basis

assets/css/compiled/main.css

@@ -2448,6 +2448,12 @@ body:has(#menu-controller:checked) {
   transition-duration: 150ms;
 }
 
+.transition-colors {
+  transition-property: color, background-color, border-color, text-decoration-color, fill, stroke;
+  transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+  transition-duration: 150ms;
+}
+
 .transition-opacity {
   transition-property: opacity;
   transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
@@ -2575,6 +2581,14 @@ body:has(#menu-controller:checked) {
   text-decoration-color: rgba(var(--color-primary-500), 1);
 }
 
+.group:hover .group-hover\:decoration-2 {
+  text-decoration-thickness: 2px;
+}
+
+.group:hover .group-hover\:underline-offset-2 {
+  text-underline-offset: 2px;
+}
+
 .group:hover .group-hover\:opacity-100 {
   opacity: 1;
 }

config/_default/menus.en.toml

@@ -1,7 +1,7 @@
 # -- Main Menu --
 # The main menu is displayed in the header at the top of the page.
 # Acceptable parameters are name, pageRef, page, url, title, weight.
-# 
+#
 # The simplest menu configuration is to provide:
 #   name = The name to be displayed for this menu link
 #   pageRef = The identifier of the page or section to link to
@@ -25,6 +25,12 @@
   pageRef = "tags"
   weight = 30
 
+[[main]]
+  identifier = "search"
+  weight = 99
+  [main.params]
+    action = "search"
+    icon = "search"
 
 # -- Footer Menu --
 # The footer menu is displayed at the bottom of the page, just before

exampleSite/config/_default/menus.en.toml

@@ -1,7 +1,7 @@
 # -- Main Menu --
 # The main menu is displayed in the header at the top of the page.
 # Acceptable parameters are name, pageRef, page, url, title, weight.
-# 
+#
 # The simplest menu configuration is to provide:
 #   name = The name to be displayed for this menu link
 #   pageRef = The identifier of the page or section to link to
@@ -24,12 +24,22 @@
   name = "Users"
   pageRef = "users"
   weight = 30
-  
+
 [[main]]
   name = "GitHub"
   url = "https://github.com/jpanther/congo"
   weight = 40
+  [main.params]
+    icon = "github"
+    showName = false
+    target = "_blank"
 
+[[main]]
+  identifier = "search"
+  weight = 99
+  [main.params]
+    action = "search"
+    icon = "search"
 
 # -- Footer Menu --
 # The footer menu is displayed at the bottom of the page, just before

exampleSite/content/docs/getting-started/index.md

@@ -3,7 +3,7 @@ title: "Getting Started"
 date: 2020-08-15
 draft: false
 description: "Learn how to get started using the Congo theme."
-summary: "This section assumes you have already installed the Congo theme and are ready to start with basic configuration tasks."
+summary: "This section assumes you have already installed the Congo theme and are ready to start with basic configuration tasks like selecting a colour scheme, menu and content structure."
 slug: "getting-started"
 tags: ["installation", "docs"]
 ---
@@ -174,7 +174,7 @@ Congo has two menus that can be customised to suit the content and layout of you
 Both menus are configured in the `menus.en.toml` file. Similarly to the languages config file, if you wish to use another language, rename this file and replace `en` with the language code you wish to use.
 
 ```toml
-# config/_default/menus.toml
+# config/_default/menus.en.toml
 
 [[main]]
   name = "Blog"
@@ -186,18 +186,38 @@ Both menus are configured in the `menus.en.toml` file. Similarly to the language
   pageRef = "topics"
   weight = 20
 
+[[main]]
+  name = "GitHub"
+  url = "https://github.com/jpanther/congo"
+  weight = 30
+  [main.params]
+    icon = "github"
+    showName = false
+    target = "_blank"
+
+[[main]]
+  identifier = "search"
+  weight = 99
+  [main.params]
+    action = "search"
+    icon = "search"
+
 [[footer]]
   name = "Privacy"
-  url = "https://external-link"
+  pageRef = "privacy"
 ```
 
 The `name` parameter specifies the text that is used in the menu link. You can also optionally provide a `title` which fills the HTML title attribute for the link.
 
 The `pageRef` parameter allows you to easily reference Hugo content pages and taxonomies. It is the quickest way to configure the menu as you can simply refer to any Hugo content item and it will automatically build the correct link. To link to external URLs, the `url` parameter can be used.
 
+Further customisation can be achieved through the use of special theme parameters. Providing `params` within a link allows the addition of an `icon`, the ability to toggle the link text with `showName` and to optionally set a `target` for the URL. In the example above, the GitHub link will only display as an icon and will open the link in a new window.
+
+Finally, there is a special case for theme links, which are denoted using the `action` parameter. When this parameter has the value of `search` it will be replaced with a link to the site search. It allows all the same custom parameters as other links and can be styled with an icon or text name.
+
 Menu links will be sorted from lowest to highest `weight`, and then alphabetically by `name`.
 
-Both menus are completely optional and can be commented out if not required. Use the template provided in the file as a guide.
+Both menus are completely optional and can be commented out if not required. Use the template provided in the default file as a guide.
 
 ## Detailed configuration
 

layouts/partials/footer.html

@@ -1,3 +1,4 @@
+{{ $searchCount := 0 }}
 <footer class="py-10 print:hidden">
   {{/* Footer menu */}}
   {{ if .Site.Menus.footer }}
@@ -5,14 +6,48 @@
       <ul class="flex flex-col list-none sm:flex-row">
         {{ range .Site.Menus.footer }}
           <li
-            class="mb-1 ltr:text-right rtl:text-left sm:mb-0 ltr:sm:mr-7 ltr:sm:last:mr-0 rtl:sm:ml-7 rtl:sm:last:ml-0"
+            class="mb-1 group ltr:text-right rtl:text-left sm:mb-0 ltr:sm:mr-7 ltr:sm:last:mr-0 rtl:sm:ml-7 rtl:sm:last:ml-0"
           >
-            <a
+            {{ if eq .Params.action "search" }}
-              class="decoration-primary-500 hover:underline hover:decoration-2 hover:underline-offset-2"
+              {{ $searchCount = add $searchCount 1 }}
-              href="{{ .URL }}"
+              {{ if $.Site.Params.enableSearch | default false }}
-              title="{{ .Title }}"
+                <button
-              >{{ .Name | markdownify | emojify }}</a
+                  id="search-button-f{{ $searchCount }}"
-            >
+                  title="{{ .Title | default (i18n "search.open_button_title") }}"
+                >
+                  {{ with .Params.icon }}
+                    <span
+                      class="transition-colors group-dark:hover:text-primary-400 group-hover:text-primary-600"
+                    >
+                      {{ partial "icon.html" . }}
+                    </span>
+                  {{ end }}{{ if .Params.showName | default true }}
+                    <span
+                      class="decoration-primary-500 group-hover:underline group-hover:decoration-2 group-hover:underline-offset-2"
+                      >{{ .Name | markdownify | emojify }}</span
+                    >
+                  {{ end }}
+                </button>
+              {{ end }}
+            {{ else }}
+              <a
+                href="{{ .URL }}"
+                title="{{ .Title }}"
+                {{ with .Params.target }}target="{{ . }}"{{ end }}
+                >{{ with .Params.icon }}
+                  <span
+                    class="transition-colors group-dark:hover:text-primary-400 group-hover:text-primary-600"
+                  >
+                    {{ partial "icon.html" . }}
+                  </span>
+                {{ end }}{{ if .Params.showName | default true }}
+                  <span
+                    class="decoration-primary-500 group-hover:underline group-hover:decoration-2 group-hover:underline-offset-2"
+                    >{{ .Name | markdownify | emojify }}</span
+                  >
+                {{ end }}</a
+              >
+            {{ end }}
           </li>
         {{ end }}
       </ul>

layouts/partials/header/basic.html

@@ -1,3 +1,4 @@
+{{ $searchCount := 0 }}
 <header class="py-6 font-semibold text-neutral-900 dark:text-neutral print:hidden sm:py-10">
   <nav class="flex items-start justify-between sm:items-center">
     {{/* Site logo/title */}}
@@ -7,29 +8,67 @@
     </div>
     {{/* Main menu */}}
     {{ if or .Site.Menus.main (.Site.Params.enableSearch | default false) }}
-      <ul class="flex list-none flex-col ltr:text-right rtl:text-left sm:flex-row">
+      <ul class="flex flex-col list-none ltr:text-right rtl:text-left sm:flex-row">
         {{ if .Site.Menus.main }}
           {{ range .Site.Menus.main }}
-            <li class="mb-1 sm:mb-0 ltr:sm:mr-7 ltr:sm:last:mr-0 rtl:sm:ml-7 rtl:sm:last:ml-0">
+            <li
-              <a
+              class="mb-1 group sm:mb-0 ltr:sm:mr-7 ltr:sm:last:mr-0 rtl:sm:ml-7 rtl:sm:last:ml-0"
-                class="decoration-primary-500 hover:underline hover:decoration-2 hover:underline-offset-2"
+            >
-                href="{{ .URL }}"
+              {{ if eq .Params.action "search" }}
-                title="{{ .Title }}"
+                {{ $searchCount = add $searchCount 1 }}
-                >{{ .Name | markdownify | emojify }}</a
+                {{ if $.Site.Params.enableSearch | default false }}
-              >
+                  <button
+                    id="search-button-m{{ $searchCount }}"
+                    title="{{ .Title | default (i18n "search.open_button_title") }}"
+                  >
+                    {{ with .Params.icon }}
+                      <span
+                        class="transition-colors group-dark:hover:text-primary-400 group-hover:text-primary-600"
+                      >
+                        {{ partial "icon.html" . }}
+                      </span>
+                    {{ end }}{{ if .Params.showName | default true }}
+                      <span
+                        class="decoration-primary-500 group-hover:underline group-hover:decoration-2 group-hover:underline-offset-2"
+                        >{{ .Name | markdownify | emojify }}</span
+                      >
+                    {{ end }}
+                  </button>
+                {{ end }}
+              {{ else }}
+                <a
+                  href="{{ .URL }}"
+                  title="{{ .Title }}"
+                  {{ with .Params.target }}target="{{ . }}"{{ end }}
+                  >{{ with .Params.icon }}
+                    <span
+                      class="transition-colors group-dark:hover:text-primary-400 group-hover:text-primary-600"
+                    >
+                      {{ partial "icon.html" . }}
+                    </span>
+                  {{ end }}{{ if .Params.showName | default true }}
+                    <span
+                      class="decoration-primary-500 group-hover:underline group-hover:decoration-2 group-hover:underline-offset-2"
+                      >{{ .Name | markdownify | emojify }}</span
+                    >
+                  {{ end }}</a
+                >
+              {{ end }}
             </li>
           {{ end }}
-        {{ end }}
+          {{ if and ($.Site.Params.enableSearch | default false) (eq $searchCount 0) }}
-        {{ if .Site.Params.enableSearch | default false }}
+            <li
-          <li class="ltr:sm:mr-7 ltr:sm:last:mr-0 rtl:sm:ml-7 rtl:sm:last:ml-0">
+              class="mb-1 group sm:mb-0 ltr:sm:mr-7 ltr:sm:last:mr-0 rtl:sm:ml-7 rtl:sm:last:ml-0"
-            <button
-              id="search-button"
-              class="text-base hover:text-primary-600 dark:hover:text-primary-400"
-              title="{{ i18n "search.open_button_title" }}"
             >
-              {{ partial "icon.html" "search" }}
+              <button id="search-button-m0" title="{{ i18n "search.open_button_title" }}">
-            </button>
+                <span
-          </li>
+                  class="transition-colors group-dark:hover:text-primary-400 group-hover:text-primary-600"
+                >
+                  {{ partial "icon.html" "search" }}
+                </span>
+              </button>
+            </li>
+          {{ end }}
         {{ end }}
       </ul>
     {{ end }}

layouts/partials/header/hamburger.html

@@ -1,3 +1,4 @@
+{{ $searchCount := 0 }}
 <header class="py-6 font-semibold text-neutral-900 dark:text-neutral print:hidden sm:py-10">
   <nav class="flex items-start justify-between sm:items-center">
     {{/* Site logo/title */}}
@@ -26,26 +27,60 @@
             </li>
             {{ if .Site.Menus.main }}
               {{ range .Site.Menus.main }}
-                <li class="mb-1">
+                <li class="mb-1 group">
-                  <a
+                  {{ if eq .Params.action "search" }}
-                    class="decoration-primary-500 hover:underline hover:decoration-2 hover:underline-offset-2"
+                    {{ $searchCount = add $searchCount 1 }}
-                    href="{{ .URL }}"
+                    {{ if $.Site.Params.enableSearch | default false }}
-                    title="{{ .Title }}"
+                      <button
-                    >{{ .Name | markdownify | emojify }}</a
+                        id="search-button-m{{ $searchCount }}"
-                  >
+                        title="{{ .Title | default (i18n "search.open_button_title") }}"
+                      >
+                        {{ with .Params.icon }}
+                          <span
+                            class="transition-colors group-dark:hover:text-primary-400 group-hover:text-primary-600"
+                          >
+                            {{ partial "icon.html" . }}
+                          </span>
+                        {{ end }}{{ if .Params.showName | default true }}
+                          <span
+                            class="decoration-primary-500 group-hover:underline group-hover:decoration-2 group-hover:underline-offset-2"
+                            >{{ .Name | markdownify | emojify }}</span
+                          >
+                        {{ end }}
+                      </button>
+                    {{ end }}
+                  {{ else }}
+                    <a
+                      href="{{ .URL }}"
+                      title="{{ .Title }}"
+                      {{ with .Params.target }}target="{{ . }}"{{ end }}
+                      >{{ with .Params.icon }}
+                        <span
+                          class="transition-colors group-dark:hover:text-primary-400 group-hover:text-primary-600"
+                        >
+                          {{ partial "icon.html" . }}
+                        </span>
+                      {{ end }}{{ if .Params.showName | default true }}
+                        <span
+                          class="decoration-primary-500 group-hover:underline group-hover:decoration-2 group-hover:underline-offset-2"
+                          >{{ .Name | markdownify | emojify }}</span
+                        >
+                      {{ end }}</a
+                    >
+                  {{ end }}
+                </li>
+              {{ end }}
+              {{ if and ($.Site.Params.enableSearch | default false) (eq $searchCount 0) }}
+                <li class="mb-1 group">
+                  <button id="search-button-m0" title="{{ i18n "search.open_button_title" }}">
+                    <span
+                      class="transition-colors group-dark:hover:text-primary-400 group-hover:text-primary-600"
+                    >
+                      {{ partial "icon.html" "search" }}
+                    </span>
+                  </button>
                 </li>
               {{ end }}
-            {{ end }}
-            {{ if .Site.Params.enableSearch | default false }}
-              <li>
-                <button
-                  id="search-button"
-                  class="text-base hover:text-primary-600 dark:hover:text-primary-400"
-                  title="{{ i18n "search.open_button_title" }}"
-                >
-                  {{ partial "icon.html" "search" }}
-                </button>
-              </li>
             {{ end }}
           </ul>
         </div>

layouts/partials/header/hybrid.html

@@ -1,3 +1,4 @@
+{{ $searchCount := 0 }}
 <header class="py-6 font-semibold text-neutral-900 dark:text-neutral print:hidden sm:py-10">
   <nav class="flex items-start justify-between sm:items-center">
     {{/* Site logo/title */}}
@@ -26,26 +27,60 @@
             </li>
             {{ if .Site.Menus.main }}
               {{ range .Site.Menus.main }}
-                <li class="mb-1">
+                <li class="mb-1 group">
-                  <a
+                  {{ if eq .Params.action "search" }}
-                    class="decoration-primary-500 hover:underline hover:decoration-2 hover:underline-offset-2"
+                    {{ $searchCount = add $searchCount 1 }}
-                    href="{{ .URL }}"
+                    {{ if $.Site.Params.enableSearch | default false }}
-                    title="{{ .Title }}"
+                      <button
-                    >{{ .Name | markdownify | emojify }}</a
+                        id="search-button-m{{ $searchCount }}"
-                  >
+                        title="{{ .Title | default (i18n "search.open_button_title") }}"
+                      >
+                        {{ with .Params.icon }}
+                          <span
+                            class="transition-colors group-dark:hover:text-primary-400 group-hover:text-primary-600"
+                          >
+                            {{ partial "icon.html" . }}
+                          </span>
+                        {{ end }}{{ if .Params.showName | default true }}
+                          <span
+                            class="decoration-primary-500 group-hover:underline group-hover:decoration-2 group-hover:underline-offset-2"
+                            >{{ .Name | markdownify | emojify }}</span
+                          >
+                        {{ end }}
+                      </button>
+                    {{ end }}
+                  {{ else }}
+                    <a
+                      href="{{ .URL }}"
+                      title="{{ .Title }}"
+                      {{ with .Params.target }}target="{{ . }}"{{ end }}
+                      >{{ with .Params.icon }}
+                        <span
+                          class="transition-colors group-dark:hover:text-primary-400 group-hover:text-primary-600"
+                        >
+                          {{ partial "icon.html" . }}
+                        </span>
+                      {{ end }}{{ if .Params.showName | default true }}
+                        <span
+                          class="decoration-primary-500 group-hover:underline group-hover:decoration-2 group-hover:underline-offset-2"
+                          >{{ .Name | markdownify | emojify }}</span
+                        >
+                      {{ end }}</a
+                    >
+                  {{ end }}
+                </li>
+              {{ end }}
+              {{ if and ($.Site.Params.enableSearch | default false) (eq $searchCount 0) }}
+                <li class="mb-1 group">
+                  <button id="search-button-m0" title="{{ i18n "search.open_button_title" }}">
+                    <span
+                      class="transition-colors group-dark:hover:text-primary-400 group-hover:text-primary-600"
+                    >
+                      {{ partial "icon.html" "search" }}
+                    </span>
+                  </button>
                 </li>
               {{ end }}
-            {{ end }}
-            {{ if .Site.Params.enableSearch | default false }}
-              <li>
-                <button
-                  id="search-button-2"
-                  class="text-base hover:text-primary-600 dark:hover:text-primary-400"
-                  title="{{ i18n "search.open_button_title" }}"
-                >
-                  {{ partial "icon.html" "search" }}
-                </button>
-              </li>
             {{ end }}
           </ul>
         </div>
@@ -54,27 +89,52 @@
       <ul class="flex-row hidden list-none ltr:text-right rtl:text-left sm:flex">
         {{ if .Site.Menus.main }}
           {{ range .Site.Menus.main }}
-            <li class="mb-1 sm:mb-0 ltr:sm:mr-7 ltr:sm:last:mr-0 rtl:sm:ml-7 rtl:sm:last:ml-0">
+            <li
-              <a
+              class="mb-1 group sm:mb-0 ltr:sm:mr-7 ltr:sm:last:mr-0 rtl:sm:ml-7 rtl:sm:last:ml-0"
-                class="decoration-primary-500 hover:underline hover:decoration-2 hover:underline-offset-2"
+            >
-                href="{{ .URL }}"
+              {{ if eq .Params.action "search" }}
-                title="{{ .Title }}"
+                {{ $searchCount = add $searchCount 1 }}
-                >{{ .Name | markdownify | emojify }}</a
+                {{ if $.Site.Params.enableSearch | default false }}
-              >
+                  <button
+                    id="search-button-m{{ $searchCount }}"
+                    title="{{ .Title | default (i18n "search.open_button_title") }}"
+                  >
+                    {{ with .Params.icon }}
+                      <span
+                        class="transition-colors group-dark:hover:text-primary-400 group-hover:text-primary-600"
+                      >
+                        {{ partial "icon.html" . }}
+                      </span>
+                    {{ end }}{{ if .Params.showName | default true }}
+                      <span
+                        class="decoration-primary-500 group-hover:underline group-hover:decoration-2 group-hover:underline-offset-2"
+                        >{{ .Name | markdownify | emojify }}</span
+                      >
+                    {{ end }}
+                  </button>
+                {{ end }}
+              {{ else }}
+                <a
+                  href="{{ .URL }}"
+                  title="{{ .Title }}"
+                  {{ with .Params.target }}target="{{ . }}"{{ end }}
+                  >{{ with .Params.icon }}
+                    <span
+                      class="transition-colors group-dark:hover:text-primary-400 group-hover:text-primary-600"
+                    >
+                      {{ partial "icon.html" . }}
+                    </span>
+                  {{ end }}{{ if .Params.showName | default true }}
+                    <span
+                      class="decoration-primary-500 group-hover:underline group-hover:decoration-2 group-hover:underline-offset-2"
+                      >{{ .Name | markdownify | emojify }}</span
+                    >
+                  {{ end }}</a
+                >
+              {{ end }}
             </li>
           {{ end }}
         {{ end }}
-        {{ if .Site.Params.enableSearch | default false }}
-          <li class="ltr:sm:mr-7 ltr:sm:last:mr-0 rtl:sm:ml-7 rtl:sm:last:ml-0">
-            <button
-              id="search-button-1"
-              class="text-base hover:text-primary-600 dark:hover:text-primary-400"
-              title="{{ i18n "search.open_button_title" }}"
-            >
-              {{ partial "icon.html" "search" }}
-            </button>
-          </li>
-        {{ end }}
       </ul>
     {{ end }}
   </nav>