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`

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>
-    {{- end -}}
+{{- $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 -}}
-</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
+  
+  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).
+  
+  Parameters:
+  - .context (Page): The Hugo page to process
+  - .type (string): Fragment type - "content" (default), "heading", "title", or "summary"
+  
+  Returns:
+  - dict: Map of heading keys to content fragments
+  
+  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
+*/ -}}
 
-{{ $headingKeys := slice }}
-{{ $headingTitles := slice }}
+{{- /* Extract page context and fragment type */ -}}
+{{- $page := .context -}}
+{{- $type := .type | default "content" -}}
 
-{{ 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) }}
+{{- /* Initialize slices to store heading data */ -}}
+{{- $headingKeys := slice -}}    {{- /* Keys for indexing (ID#Title or just Title) */ -}}
+{{- $headingTitles := slice -}}  {{- /* HTML heading tags for content splitting */ -}}
 
-  {{ range $h2 := $h1.Headings }}
-    {{ $headingKeys = $headingKeys | append (printf "%s#%s" $h2.ID $h2.Title) }}
-    {{ $headingTitles = $headingTitles | append (printf "<h2>%s" $h2.Title) }}
-  {{ end }}
-{{ end }}
+{{- /* 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) -}}
 
-{{ $content := $page.Content | htmlUnescape }}
-{{ $len := len $headingKeys }}
-{{ $data := dict }}
+  {{- /* 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 }}