feat: exclude page from sidebar (#209)

* feat: allow excluding page from sidebar

* chore: tidy up

* docs: add instruction for excluding a page from sidebar

* feat: allow hiding sidebar for pages

* chore: add comment

assets/css/compiled/main.css

@@ -634,6 +634,9 @@ video {
 .ml-4 {
   margin-left: 1rem;
 }
+.mr-1 {
+  margin-right: 0.25rem;
+}
 .mr-2 {
   margin-right: 0.5rem;
 }
@@ -848,6 +851,9 @@ video {
 .flex-col {
   flex-direction: column;
 }
+.flex-wrap {
+  flex-wrap: wrap;
+}
 .items-start {
   align-items: flex-start;
 }
@@ -878,6 +884,17 @@ video {
 .gap-4 {
   gap: 1rem;
 }
+.gap-x-1 {
+  -moz-column-gap: 0.25rem;
+       column-gap: 0.25rem;
+}
+.gap-x-1\.5 {
+  -moz-column-gap: 0.375rem;
+       column-gap: 0.375rem;
+}
+.gap-y-2 {
+  row-gap: 0.5rem;
+}
 .overflow-auto {
   overflow: auto;
 }
@@ -1408,9 +1425,6 @@ video {
   -webkit-hyphens: auto;
           hyphens: auto;
 }
-.\[text-underline-position\:from-font\] {
-  text-underline-position: from-font;
-}
 .\[transition\:background-color_1\.5s_ease\] {
   transition: background-color 1.5s ease;
 }
@@ -2735,6 +2749,9 @@ body {
   --tw-rotate: 90deg;
   transform: translate(var(--tw-translate-x), var(--tw-translate-y)) rotate(var(--tw-rotate)) skewX(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y));
 }
+.group:hover .group-hover\:underline {
+  text-decoration-line: underline;
+}
 .group\/code:hover .group-hover\/code\:opacity-100 {
   opacity: 1;
 }

assets/js/code-copy.js

@@ -33,8 +33,8 @@ document.addEventListener('DOMContentLoaded', function () {
     // Add click event listener for copy button
     button.addEventListener('click', function (e) {
       e.preventDefault();
-      const targetId = button.getAttribute('data-clipboard-target');
-      const target = document.querySelector(targetId);
+      // Get the code target
+      const target = button.parentElement.previousElementSibling;
       let codeElement;
       if (target.tagName === 'CODE') {
         codeElement = target;
@@ -44,9 +44,12 @@ document.addEventListener('DOMContentLoaded', function () {
         codeElement = codeElements[codeElements.length - 1];
       }
       if (codeElement) {
+        let code = codeElement.innerText;
         // Replace double newlines with single newlines in the innerText
         // as each line inside <span> has trailing newline '\n'
-        const code = codeElement.innerText.replace(/\n\n/g, '\n');
+        if ("lang" in codeElement.dataset) {
+          code = code.replace(/\n\n/g, '\n');
+        }
         navigator.clipboard.writeText(code).then(function () {
           button.classList.add('copied');
           setTimeout(function () {

exampleSite/content/blog/markdown.md

@@ -2,8 +2,12 @@
 title: Markdown Syntax Guide
 date: 2020-01-01
 authors:
-  - name: John Doe
-    link: https://example.com/johndoe
+  - name: imfing
+    link: https://github.com/imfing
+    image: https://github.com/imfing.png
+  - name: Octocat
+    link: https://github.com/octocat
+    image: https://github.com/octocat.png
 tags:
   - Markdown
   - Example

exampleSite/content/docs/advanced/customization.md

@@ -47,8 +47,8 @@ The primary color of the theme can be customized by setting the `--primary-hue`
 
 List of available syntax highlighting themes are available at [Chroma Styles Gallery](https://xyproto.github.io/splash/docs/all.html). The stylesheet can be generated using the command:
 
-```bash
-$ hugo gen chromastyles --style=github
+```shell
+hugo gen chromastyles --style=github
 ```
 
 To override the default syntax highlighting theme, we can add the generated styles to the custom CSS file.
@@ -70,4 +70,4 @@ For further information, refer to the [Hugo Templates](https://gohugo.io/templat
 
 ## Further Customization
 
-Didn't find what you were looking for? Feel free to [open an issue](https://github.com/imfing/hextra/issues) or make a contribution to the theme!
+Didn't find what you were looking for? Feel free to [open a discussion](https://github.com/imfing/hextra/discussions) or make a contribution to the theme!

exampleSite/content/docs/getting-started.md

@@ -43,18 +43,18 @@ Before starting, you need to have the following software installed:
 ### Initialize a new Hugo site
 
 ```shell
-$ hugo new site my-site --format=yaml
+hugo new site my-site --format=yaml
 ```
 
 ### Configure Hextra theme via module
 
 ```shell
 # initialize hugo module
-$ cd my-site
-$ hugo mod init github.com/username/my-site
+cd my-site
+hugo mod init github.com/username/my-site
 
 # add Hextra theme
-$ hugo mod get github.com/imfing/hextra
+hugo mod get github.com/imfing/hextra
 ```
 
 Configure `hugo.yaml` to use Hextra theme by adding the following:
@@ -70,14 +70,14 @@ module:
 Create new content page for the home page and the documentation page:
 
 ```shell
-$ hugo new content/_index.md
-$ hugo new content/docs/_index.md
+hugo new content/_index.md
+hugo new content/docs/_index.md
 ```
 
 ### Preview the site locally
 
 ```shell
-$ hugo server --buildDrafts --disableFastRender
+hugo server --buildDrafts --disableFastRender
 ```
 
 Voila, your new site preview is available at `http://localhost:1313/`.
@@ -90,7 +90,7 @@ Voila, your new site preview is available at `http://localhost:1313/`.
 To update all Hugo modules in your project to their latest versions, run the following command:
 
 ```shell
-$ hugo mod get -u
+hugo mod get -u
 ```
 
 To update Hextra to the [latest released version](https://github.com/imfing/hextra/releases), run the following command:
@@ -119,7 +119,7 @@ Before starting, you need to have the following software installed:
 ### Initialize a new Hugo site
 
 ```shell
-$ hugo new site my-site --format=yaml
+hugo new site my-site --format=yaml
 ```
 
 ### Add Hextra theme as a Git submodule
@@ -139,14 +139,14 @@ theme: hextra
 Create new content page for the home page and the documentation page:
 
 ```shell
-$ hugo new content/_index.md
-$ hugo new content/docs/_index.md
+hugo new content/_index.md
+hugo new content/docs/_index.md
 ```
 
 ### Preview the site locally
 
 ```shell
-$ hugo server --buildDrafts --disableFastRender
+hugo server --buildDrafts --disableFastRender
 ```
 
 Your new site preview is available at `http://localhost:1313/`.
@@ -168,7 +168,7 @@ Failure to run this command results in the theme folder not being populated with
 To update all submodules in your repository to their latest commits, run the following command:
 
 ```shell
-$ git submodule update --remote
+git submodule update --remote
 ```
 
 To update Hextra to the latest commit, run the following command:

exampleSite/content/docs/guide/configuration.md

@@ -90,6 +90,16 @@ params:
 For the main sidebar, it is automatically generated from the structure of the content directory.
 See the [Organize Files](/docs/guide/organize-files) page for more details.
 
+To exclude a single page from the left sidebar, set the `sidebar.exclude` parameter in the front matter of the page:
+
+```yaml {filename="content/docs/guide/configuration.md"}
+---
+title: Configuration
+sidebar:
+  exclude: true
+---
+```
+
 ### Extra Links
 
 Sidebar extra links are defined under the `menu.sidebar` section in the config file:

exampleSite/content/docs/guide/shortcodes/details.md

@@ -24,7 +24,7 @@ This will be hidden by default.
 
 ## Usage
 
-````
+````markdown
 {{%/* details title="Details" */%}}
 
 This is the content of the details.
@@ -34,7 +34,7 @@ Markdown is **supported**.
 {{%/* /details */%}}
 ````
 
-````
+````markdown
 {{%/* details title="Click me to reveal" closed="true" */%}}
 
 This will be hidden by default.

exampleSite/hugo_stats.json

@@ -66,7 +66,6 @@
       "[-webkit-touch-callout:none]",
       "[counter-reset:step]",
       "[hyphens:auto]",
-      "[text-underline-position:from-font]",
       "[transition:background-color_1.5s_ease]",
       "[word-break:break-word]",
       "absolute",
@@ -241,6 +240,7 @@
       "fixed",
       "flex",
       "flex-col",
+      "flex-wrap",
       "focus:bg-white",
       "focus:outline-none",
       "focus:ring-4",
@@ -258,6 +258,8 @@
       "gap-1",
       "gap-2",
       "gap-4",
+      "gap-x-1.5",
+      "gap-y-2",
       "grid",
       "grid-cols-1",
       "group",
@@ -266,6 +268,7 @@
       "group-data-[theme=dark]:hidden",
       "group-data-[theme=light]:hidden",
       "group-hover/code:opacity-100",
+      "group-hover:underline",
       "group-open:before:rotate-90",
       "group/code",
       "group/copybtn",
@@ -407,6 +410,7 @@
       "ml-1",
       "ml-4",
       "mobile-menu-overlay",
+      "mr-1",
       "mr-2",
       "mt-1",
       "mt-1.5",

i18n/en.yaml

@@ -1,6 +1,7 @@
 backToTop: "Scroll to top"
 changeLanguage: "Change language"
 changeTheme: "Change theme"
+copyCode: "Copy code"
 copyright: "© 2023 Hextra Project."
 dark: "Dark"
 editThisPage: "Edit this page on GitHub →"

layouts/_default/_markup/render-codeblock.html

@@ -1,6 +1,7 @@
 {{- $class := .Attributes.class | default "" -}}
 {{- $filename := .Attributes.filename | default "" -}}
 {{- $lang := .Attributes.lang | default .Type -}}
+{{- $copyCode := (T "copyCode") | default "Copy code" -}}
 
 
 <div class="code-block relative mt-6 first:mt-0 group/code">
@@ -8,17 +9,14 @@
     <div class="filename">{{ $filename }}</div>
   {{- end -}}
   {{- if transform.CanHighlight $lang -}}
-    <div id="code-block-{{ .Ordinal }}">
-      {{- highlight .Inner $lang .Options -}}
-    </div>
+    <div>{{- highlight .Inner $lang .Options -}}</div>
   {{- else -}}
-    <pre><code id="code-block-{{ .Ordinal }}">{{ .Inner }}</code></pre>
+    <pre><code>{{ .Inner }}</code></pre>
   {{- end -}}
   <div class="opacity-0 transition group-hover/code:opacity-100 flex gap-1 absolute m-[11px] right-0 {{ if $filename }}top-8{{ else }}top-0{{ end }}">
     <button
       class="code-copy-btn group/copybtn transition-all active:opacity-50 bg-primary-700/5 border border-black/5 text-gray-600 hover:text-gray-900 rounded-md p-1.5 dark:bg-primary-300/10 dark:border-white/10 dark:text-gray-400 dark:hover:text-gray-50"
-      title="Copy code"
-      data-clipboard-target="#code-block-{{ .Ordinal }}"
+      title="{{ $copyCode }}"
     >
       <div class="group-[.copied]/copybtn:hidden copy-icon pointer-events-none h-4 w-4"></div>
       <div class="hidden group-[.copied]/copybtn:block success-icon pointer-events-none h-4 w-4"></div>

layouts/_default/_markup/render-image.html

@@ -1,13 +1,13 @@
 {{- $alt := .PlainText | safeHTML -}}
-{{- $lazyLoading := .Page.Site.Params.enableImagelazyLoading | default true -}}
+{{- $lazyLoading := .Page.Site.Params.enableImageLazyLoading | default true -}}
 {{- $dest := .Destination -}}
 
-{{- $isRemote := not (urls.Parse $dest).Scheme -}}
+{{- $isLocal := not (urls.Parse $dest).Scheme -}}
 {{- $isPage := and (eq .Page.Kind "page") (not .Page.BundleType) -}}
 {{- $startsWithSlash := hasPrefix $dest "/" -}}
 {{- $startsWithRelative := hasPrefix $dest "../" -}}
 
-{{- if and $dest $isRemote -}}
+{{- if and $dest $isLocal -}}
   {{- if $startsWithSlash -}}
     {{/* Images under static directory */}}
     {{- $dest = (relURL (strings.TrimPrefix "/" $dest)) -}}

layouts/blog/single.html

@@ -1,27 +1,40 @@
 {{ define "main" }}
-  <div class='mx-auto flex {{ partial "utils/page-width" . }}'>
+  <div class="mx-auto flex {{ partial `utils/page-width` . }}">
     {{ partial "sidebar.html" (dict "context" . "disableSidebar" true "displayPlaceholder" true) }}
     {{ partial "toc.html" . }}
     <article class="w-full break-words flex min-h-[calc(100vh-var(--navbar-height))] min-w-0 justify-center pb-8 pr-[calc(env(safe-area-inset-right)-1.5rem)]">
       <main class="w-full min-w-0 max-w-6xl px-6 pt-4 md:px-12">
         {{ partial "breadcrumb.html" . }}
         <h1 class="mt-2 text-4xl font-bold tracking-tight text-slate-900 dark:text-slate-100">{{ .Title }}</h1>
-        {{ with $date := .Date }}
-          <div class="mt-4 mb-16 text-gray-500 text-sm">
-            {{ partial "utils/format-date" $date }}
-            {{- if $.Params.authors }}&nbsp;by&nbsp;{{ end -}}
+        <div class="mt-4 mb-16 text-gray-500 text-sm flex items-center flex-wrap gap-y-2">
+          {{- with $date := .Date }}<span class="mr-1">{{ partial "utils/format-date" $date }}</span>{{ end -}}
+          {{- $lazyLoading := site.Params.enableImageLazyLoading | default true -}}
+          {{ if and .Date .Params.authors }}<span class="mx-1">·</span>{{ end -}}
           {{- with $.Params.authors -}}
             {{- range $i, $author := . -}}
-                {{- if $i }},{{ end -}}
-                {{- if $author.link -}}
-                  <a href="{{ $author.link }}" target="_blank" class="mx-1 text-current underline [text-underline-position:from-font] decoration-from-font">{{ $author.name }}</a>
+              {{- if reflect.IsMap $author -}}
+                {{- if and $i (not $author.image) }}<span class="mr-1">,</span>{{ end -}}
+                <a
+                  {{ with $author.link }}href="{{ . }}" target="_blank"{{ end }}
+                  class="group inline-flex items-center text-current gap-x-1.5 mx-1"
+                  {{ with $author.name }}title="{{ . }}"{{ end }}
+                >
+                  {{- with $image := $author.image }}
+                    {{- $isLocal := not (urls.Parse $image).Scheme -}}
+                    {{- $startsWithSlash := hasPrefix $image "/" -}}
+                    {{- if and $isLocal $startsWithSlash }}
+                      {{- $image = (relURL (strings.TrimPrefix "/" $image)) -}}
+                    {{ end -}}
+                    <img src="{{ $image | safeURL }}" alt="{{ $author.name }}" class="inline-block h-4 w-4 rounded-full" {{ if $lazyLoading }}loading="lazy"{{ end }} />
+                  {{ end -}}
+                  <div class="group-hover:underline">{{ $author.name }}</div>
+                </a>
               {{- else -}}
-                  <span>{{ $author.name }}</span>
+                {{- if $i }}<span class="mr-1">,</span>{{ end -}}<span class="mx-1">{{ $author }}</span>
               {{- end -}}
             {{- end -}}
           {{- end -}}
         </div>
-        {{ end }}
         <div class="content">
           {{ .Content }}
         </div>

layouts/partials/footer.html

@@ -36,9 +36,11 @@
 
 {{- define "theme-credit" -}}
   <a class="flex text-sm items-center gap-1 text-current" target="_blank" rel="noopener noreferrer" title="Hextra GitHub Homepage" href="https://github.com/imfing/hextra">
-    <span
-      >{{ . | safeHTML }}
-      {{- partial "utils/icon.html" (dict "name" "hextra" "attributes" "height=1em class=\"inline-block ml-1 align-text-bottom\"") -}}
+    <span>
+      {{- . | markdownify -}}
+      {{- if strings.Contains . "Hextra" -}}
+        {{- partial "utils/icon.html" (dict "name" "hextra" "attributes" `height=1em class="inline-block ml-1 align-text-bottom"`) -}}
+      {{- end -}}
     </span>
   </a>
 {{- end -}}

layouts/partials/sidebar.html

@@ -6,9 +6,14 @@
 {{- $sidebarClass := cond $disableSidebar (cond $displayPlaceholder "md:hidden xl:block" "md:hidden") "md:sticky" -}}
 
 {{- $navRoot := cond (eq site.Home.Type "docs") site.Home $context.FirstSection -}}
-{{- $navPages := union $navRoot.RegularPages $navRoot.Sections -}}
 {{- $pageURL := $context.RelPermalink -}}
 
+{{/* EXPERIMENTAL */}}
+{{- if .context.Params.sidebar.hide -}}
+  {{- $disableSidebar = true -}}
+  {{- $displayPlaceholder = true -}}
+{{- end -}}
+
 
 <div class="mobile-menu-overlay [transition:background-color_1.5s_ease] fixed inset-0 z-10 bg-black/80 dark:bg-black/60 hidden"></div>
 <aside class="sidebar-container flex flex-col print:hidden md:top-16 md:shrink-0 md:w-64 md:self-start max-md:[transform:translate3d(0,-100%,0)] {{ $sidebarClass }}">
@@ -68,8 +73,14 @@
   {{- $toc := .toc | default false -}}
 
   {{- with $items := union .context.RegularPages .context.Sections -}}
+    {{- $items = where $items "Params.sidebar.exclude" "!=" true -}}
     {{- if eq $level 0 -}}
       {{- range $items.ByWeight }}
+        {{- if .Params.sidebar.separator -}}
+          <li class="[word-break:break-word] mt-5 mb-2 px-2 py-1.5 text-sm font-semibold text-gray-900 first:mt-0 dark:text-gray-100">
+            <span class="cursor-default">{{ .LinkTitle }}</span>
+          </li>
+        {{- else -}}
           {{- $active := eq $pageURL .RelPermalink -}}
           {{- $shouldOpen := or (.Params.sidebar.open) (.IsAncestor $page) $active | default true }}
           <li class="{{ if $shouldOpen }}open{{ end }}">
@@ -80,6 +91,7 @@
             {{- template "sidebar-tree" dict "context" . "page" $page "pageURL" $pageURL "level" (add $level 1) "toc" $toc -}}
           </li>
         {{- end -}}
+      {{- end -}}
     {{- else -}}
       <div class="ltr:pr-0 overflow-hidden">
         <ul class='relative flex flex-col gap-1 before:absolute before:inset-y-1 before:w-px before:bg-gray-200 before:content-[""] ltr:ml-3 ltr:pl-3 ltr:before:left-0 rtl:mr-3 rtl:pr-3 rtl:before:right-0 dark:before:bg-neutral-800'>
@@ -111,7 +123,7 @@
             <li>
               <a
                 href="#{{ anchorize .ID }}"
-                class="flex rounded px-2 py-1.5 text-sm transition-colors [word-break:break-word] cursor-pointer [-webkit-tap-highlight-color:transparent] [-webkit-touch-callout:none] contrast-more:border flex gap-2 before:opacity-25 before:content-['#'] text-gray-500 hover:bg-gray-100 hover:text-gray-900 dark:text-neutral-400 dark:hover:bg-primary-100/5 dark:hover:text-gray-50 contrast-more:text-gray-900 contrast-more:dark:text-gray-50 contrast-more:border-transparent contrast-more:hover:border-gray-900 contrast-more:dark:hover:border-gray-50"
+                class="flex rounded px-2 py-1.5 text-sm transition-colors [word-break:break-word] cursor-pointer [-webkit-tap-highlight-color:transparent] [-webkit-touch-callout:none] contrast-more:border gap-2 before:opacity-25 before:content-['#'] text-gray-500 hover:bg-gray-100 hover:text-gray-900 dark:text-neutral-400 dark:hover:bg-primary-100/5 dark:hover:text-gray-50 contrast-more:text-gray-900 contrast-more:dark:text-gray-50 contrast-more:border-transparent contrast-more:hover:border-gray-900 contrast-more:dark:hover:border-gray-50"
               >
                 {{- .Title -}}
               </a>
@@ -153,17 +165,13 @@
     {{- with .context }}
       {{- if or .RegularPages .Sections }}
         <span class="hextra-sidebar-collapsible-button">
-          {{- template "sidebear-collapsible-button" -}}
+          {{- template "sidebar-collapsible-button" -}}
         </span>
       {{- end }}
     {{ end -}}
   </a>
 {{- end -}}
 
-{{- define "sidebar-separator" -}}
-  <div class="mt-4 border-t py-4 dark:border-neutral-800 contrast-more:border-neutral-400 dark:contrast-more:border-neutral-400" />
-{{- end -}}
-
-{{- define "sidebear-collapsible-button" -}}
+{{- define "sidebar-collapsible-button" -}}
   <svg fill="none" viewBox="0 0 24 24" stroke="currentColor" class="h-[18px] min-w-[18px] rounded-sm p-0.5 hover:bg-gray-800/5 dark:hover:bg-gray-100/5"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7" class="origin-center transition-transform rtl:-rotate-180"></path></svg>
 {{- end -}}

layouts/shortcodes/card.html

@@ -79,3 +79,4 @@
     <div class="line-clamp-3 text-sm font-normal text-gray-500 dark:text-gray-400 px-4 mb-4 mt-2">{{- $subtitle | markdownify -}}</div>
   {{- end -}}
 </a>
+{{- /* Strip trailing newline. */ -}}

layouts/shortcodes/cards.html

@@ -1,5 +1,5 @@
 {{ $rows := .Get "rows" | default "3" }}
 
 <div class="hextra-cards mt-4 gap-4 grid not-prose" style="--rows: {{ $rows }};">
-  {{ .Inner }}
+  {{- .Inner -}}
 </div>

layouts/shortcodes/include.html

@@ -0,0 +1,22 @@
+{{- /*
+https://github.com/gohugoio/gohugoioTheme/blob/master/layouts/shortcodes/include.html
+
+Renders the page using the RenderShortcode method on the Page object.
+
+You must call this shortcode using the {{% %}} notation.
+
+@param {string} (postional parameter 0) The path to the page, relative to the content directory.
+@returns template.HTML
+
+@example {{% include "functions/_common/glob-patterns" %}}
+*/}}
+
+{{- with .Get 0 }}
+  {{- with site.GetPage . }}
+    {{- .RenderShortcodes }}
+  {{- else }}
+    {{- errorf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }}
+  {{- end }}
+{{- else }}
+  {{- errorf "The %q shortcode requires a positional parameter indicating the path of the file to include. See %s" .Name .Position }}
+{{- end }}