chore: enhance tags appearance in toc and minor updates (#739)

* chore: remove standard development mode command from CLAUDE.md

* docs(toc): add TOC scroll functionality documentation

- Added detailed comments to toc-scroll.js explaining the purpose and functionality of the TOC scroll spy feature.
- Clarified the requirements for proper operation, including the need for a .hextra-toc element and matching heading IDs.

* refactor(fragments): enhance fragment processing and documentation

- Improved the fragments.html partial to better handle page content splitting into searchable fragments based on headings.
- Added comprehensive documentation within the file, detailing parameters, return values, and examples for clarity.
- Updated content handling to ensure whitespace is trimmed

* refactor(tags): enhance tag rendering and styling in toc

- Updated the tags.html partial to utilize a context variable for improved accessibility.
- Enhanced the styling of tag links for better visual consistency across different themes.
- Modified toc.html and list.html to pass the context to the tags partial, ensuring consistent rendering.

* chore: run `task css`

CLAUDE.md

@@ -14,9 +14,6 @@ Hextra is a modern, responsive Hugo theme designed for creating documentation we
 # Start development server with theme reloading (recommended for theme development)
 npm run dev:theme
 
-# Standard development mode
-npm run dev
-
 # Using Task runner
 task dev
 ```

assets/js/toc-scroll.js

@@ -1,4 +1,12 @@
-// TOC Scroll Highlight
+/**
+ * TOC Scroll - Highlights active TOC links based on visible headings
+ * 
+ * Uses Intersection Observer to track heading visibility and applies
+ * 'hextra-toc-active' class to corresponding TOC links. Selects the
+ * topmost heading when multiple are visible.
+ * 
+ * Requires: .hextra-toc element, matching heading IDs, toc.css styles
+ */
 document.addEventListener("DOMContentLoaded", function () {
   const toc = document.querySelector(".hextra-toc");
   if (!toc) return;

exampleSite/hugo_stats.json

@@ -334,6 +334,8 @@
       "hx:gap-2",
       "hx:gap-4",
       "hx:gap-x-1.5",
+      "hx:gap-x-2",
+      "hx:gap-y-1",
       "hx:gap-y-2",
       "hx:grid",
       "hx:grid-cols-1",
@@ -440,7 +442,6 @@
       "hx:max-w-[min(calc(100vw-2rem),calc(100%+20rem))]",
       "hx:max-w-none",
       "hx:max-xl:hidden",
-      "hx:mb-1",
       "hx:mb-10",
       "hx:mb-12",
       "hx:mb-16",

layouts/_partials/tags.html

@@ -1,7 +1,7 @@
-<p class="hx:opacity-50 hx:text-sm hx:leading-7">
-  {{- range $tag := .Params.tags -}}
-    {{- with $.Site.GetPage (printf "/tags/%s" $tag) -}}
-      <a class="hx:inline-block hx:mr-2" href="{{ .RelPermalink }}">#{{ .Title }}</a>
+{{- $context := .context -}}
+
+{{- range $tag := $context.Params.tags -}}
+  {{- with $context.Site.GetPage (printf "/tags/%s" $tag) -}}
+    <a class="hx:inline-block hx:whitespace-nowrap hx:mr-2 hx:text-gray-500 hx:hover:text-gray-900 hx:dark:text-gray-400 hx:dark:hover:text-gray-100 hx:contrast-more:text-gray-800 hx:contrast-more:dark:text-gray-50" href="{{ .RelPermalink }}">#{{ .Title }}</a>
   {{- end -}}
-  {{- end -}}
-</p>
+{{- end -}}

layouts/_partials/toc.html

@@ -20,19 +20,20 @@
 
       {{- $borderClass := "hx:mt-8 hx:border-t hx:bg-white hx:pt-8 hx:shadow-[0_-12px_16px_white] hx:dark:bg-dark hx:dark:shadow-[0_-12px_16px_#111]" -}}
 
-      {{- if and site.Params.toc.displayTags .Params.tags -}}
-        <div class="{{ $borderClass }} hx:sticky hx:bottom-0 hx:flex hx:flex-col hx:items-start hx:gap-2 hx:border-gray-200 hx:dark:border-neutral-800 hx:contrast-more:border-t hx:contrast-more:border-neutral-400 hx:contrast-more:shadow-none hx:contrast-more:dark:border-neutral-400">
-          <p class="hx:mb-1 hx:font-semibold hx:tracking-tight">{{ $tags }}</p>
-          {{ partial "tags.html" . }}
-        </div>
-      {{- end -}}
-
       {{- if not .Fragments.Headings -}}
         {{- $borderClass = "" -}}
       {{- end -}}
 
       {{/* TOC bottom part */}}
       <div class="{{ $borderClass }} hx:sticky hx:bottom-0 hx:flex hx:flex-col hx:items-start hx:gap-2 hx:pb-8 hx:border-gray-200 hx:dark:border-neutral-800 hx:contrast-more:border-t hx:contrast-more:border-neutral-400 hx:contrast-more:shadow-none hx:contrast-more:dark:border-neutral-400">
+        {{- if and site.Params.toc.displayTags .Params.tags -}}
+          <div class="hx:flex hx:items-start hx:gap-x-2 hx:font-medium hx:text-xs">
+            <div class="hx:text-gray-500 hx:dark:text-gray-400 hx:contrast-more:text-gray-800 hx:contrast-more:dark:text-gray-50">{{ $tags }}</div>
+            <div class="hx:flex hx:flex-wrap hx:gap-y-1">
+              {{ partial "tags.html" (dict "context" .) }}
+            </div>
+          </div>
+        {{- end -}}
         {{- if site.Params.editURL.enable -}}
           {{- $editURL := site.Params.editURL.base | default "" -}}
           {{- with .Params.editURL -}}

layouts/_partials/utils/fragments.html

@@ -1,32 +1,74 @@
-{{/* Split page raw content into fragments */}}
-{{ $page := .context }}
-{{ $type := .type | default "content" }}
+{{- /*
+  fragments.html - Split page content into searchable fragments
   
-{{ $headingKeys := slice }}
-{{ $headingTitles := slice }}
+  This partial processes a Hugo page and splits its content into fragments based on headings,
+  creating a data structure suitable for search indexing. It supports different fragment types
+  and handles hierarchical heading structures (h1, h2).
   
-{{ range $h1 := $page.Fragments.Headings }}
-  {{ if eq $h1.Title "" }}
-    {{ $headingKeys = $headingKeys | append $h1.Title }}
-  {{ else }}
-    {{ $headingKeys = $headingKeys | append (printf "%s#%s" $h1.ID $h1.Title) }}
-  {{ end }}
-  {{ $headingTitles = $headingTitles | append (printf "<h1>%s" $h1.Title) }}
+  Parameters:
+  - .context (Page): The Hugo page to process
+  - .type (string): Fragment type - "content" (default), "heading", "title", or "summary"
   
-  {{ range $h2 := $h1.Headings }}
-    {{ $headingKeys = $headingKeys | append (printf "%s#%s" $h2.ID $h2.Title) }}
-    {{ $headingTitles = $headingTitles | append (printf "<h2>%s" $h2.Title) }}
-  {{ end }}
-{{ end }}
+  Returns:
+  - dict: Map of heading keys to content fragments
   
-{{ $content := $page.Content | htmlUnescape }}
-{{ $len := len $headingKeys }}
-{{ $data := dict }}
+  Example:
+  Input page with content:
+    # Introduction
+    This is the intro text.
+    ## Setup
+    Setup instructions here.
+    # Configuration  
+    Config details here.
+  
+  Output (type "content"):
+  {
+    "": "This is the intro text.",
+    "intro#Introduction": "This is the intro text. Setup instructions here.",
+    "setup#Setup": "Setup instructions here.", 
+    "config#Configuration": "Config details here."
+  }
+  
+  Fragment types:
+  - "content": Splits page content by headings (default)
+  - "heading": Returns heading keys with empty content
+  - "title": Returns empty content (title handled elsewhere)
+  - "summary": Returns page summary only
+*/ -}}
+
+{{- /* Extract page context and fragment type */ -}}
+{{- $page := .context -}}
+{{- $type := .type | default "content" -}}
+
+{{- /* Initialize slices to store heading data */ -}}
+{{- $headingKeys := slice -}}    {{- /* Keys for indexing (ID#Title or just Title) */ -}}
+{{- $headingTitles := slice -}}  {{- /* HTML heading tags for content splitting */ -}}
+
+{{- /* Process all h1 headings and their nested h2 headings */ -}}
+{{- range $h1 := $page.Fragments.Headings -}}
+  {{- /* Handle h1 headings - empty titles get special treatment */ -}}
+  {{- if eq $h1.Title "" -}}
+    {{- $headingKeys = $headingKeys | append $h1.Title -}}
+  {{- else -}}
+    {{- $headingKeys = $headingKeys | append (printf "%s#%s" $h1.ID $h1.Title) -}}
+  {{- end -}}
+  {{- $headingTitles = $headingTitles | append (printf "<h1>%s" $h1.Title) -}}
+
+  {{- /* Process nested h2 headings */ -}}
+  {{- range $h2 := $h1.Headings -}}
+    {{- $headingKeys = $headingKeys | append (printf "%s#%s" $h2.ID $h2.Title) -}}
+    {{- $headingTitles = $headingTitles | append (printf "<h2>%s" $h2.Title) -}}
+  {{- end -}}
+{{- end -}}
+
+{{- $content := $page.Content | htmlUnescape -}}
+{{- $len := len $headingKeys -}}
+{{- $data := dict -}}
 
 {{ if eq $type "content" }}
   {{/* Include full content of the page */}}
   {{ if eq $len 0 }}
-    {{ $data = $data | merge (dict "" ($page.Plain | htmlUnescape | chomp)) }}
+    {{ $data = $data | merge (dict "" ($page.Plain | htmlUnescape | strings.TrimSpace)) }}
   {{ else }}
     {{/* Split the raw content from bottom to top */}}
     {{ range seq $len }}
@@ -35,12 +77,12 @@
       {{ $headingTitle := index $headingTitles $i }}
 
       {{ if eq $i 0 }}
-        {{ $data = $data | merge (dict $headingKey ($content | plainify | htmlUnescape | chomp)) }}
+        {{ $data = $data | merge (dict $headingKey ($content | plainify | htmlUnescape | strings.TrimSpace)) }}
       {{ else }}
         {{ $parts := split $content (printf "%s" $headingTitle) }}
-        {{ $lastPart := index $parts (sub (len $parts) 1) }}
+        {{ $lastPart := index $parts (sub (len $parts) 1) | strings.TrimSpace }}
 
-        {{ $data = $data | merge (dict $headingKey ($lastPart | plainify | htmlUnescape | chomp)) }}
+        {{ $data = $data | merge (dict $headingKey ($lastPart | plainify | htmlUnescape | strings.TrimSpace)) }}
         {{ $content = strings.TrimSuffix $lastPart $content }}
         {{ $content = strings.TrimSuffix (printf "%s" $headingTitle) $content }}
       {{ end }}
@@ -56,7 +98,7 @@
   {{/* Use empty data object since title is included in search-data.json */}}
   {{ $data = $data | merge (dict "" "") }}
 {{ else if (eq $type "summary" ) }}
-  {{ $data = $data | merge (dict "" ($page.Summary | plainify | htmlUnescape | chomp)) }}
+  {{ $data = $data | merge (dict "" ($page.Summary | plainify | htmlUnescape | strings.TrimSpace)) }}
 {{ end }}
 
 {{ return $data }}

layouts/blog/list.html

@@ -14,7 +14,9 @@
           <div class="hx:mb-10">
             <h3><a style="color: inherit; text-decoration: none;" class="hx:block hx:font-semibold hx:mt-8 hx:text-2xl " href="{{ .RelPermalink }}">{{ .Title }}</a></h3>
             {{ if site.Params.blog.list.displayTags }}
-              {{ partial "tags.html" . }}
+              <div class="hx:text-sm hx:leading-7">
+                {{ partial "tags.html" (dict "context" .) }}
+              </div>
             {{ end }}
             <p class="hx:opacity-80 hx:mt-4 hx:leading-7">{{- partial "utils/page-description" . -}}</p>
             <p class="hx:opacity-80 hx:mt-1 hx:leading-7">