wompmacho/hugo-framework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

migrate to decoupled Blowfish layout, fix TOC scrollspy, and update docs

Browse Source 
- Theme Decoupling & Cleanup:
      - Fully decoupled and vendored the Blowfish theme directly into root directories (layouts/,
  assets/, static/, data/, i18n/).
      - De-registered and cleaned up legacy Git submodules (themes/blowfish, themes/hugo-admonitions)
  from the Git index to protect the build from upstream breakages.
      - Configured .gitignore to ignore development preview symlinks (content, static,
  config/_default/menus.en.toml), build folders (public/, resources/), and locks.

    - TOC & Layout Fixes:
      - Replaced the custom layouts/_default/single.html template with the Blowfish default to restore
  native container widths and the side-by-side flex layout.
      - Restored TOC to float on the right sidebar on desktop viewports and render inline on mobile
  viewports.
      - Fixed a parameter resolution bug in layouts/partials/toc.html by checking both .Site.Params.
  smartTOC and .Site.Params.article.smartTOC (where it is defined in params.toml).
      - Upgraded the TOC scrollspy JavaScript to target all '#TableOfContents' containers on the page,
  enabling highlight tracking on both desktop and mobile layouts.

    - Documentation Updates (README.md):
      - Restored YAML front matter metadata block at the top.
      - Added detailed notes on the CI/CD build process and Gitea runner deployment targets
  (/srv/www/docs-public and /srv/www/docs-private).
      - Added a categorized and sorted "Shortcodes Quick Reference" table at the top of the shortcodes
  section (ordered by Custom, Hugo Default, and Blowfish).
      - Documented custom shortcodes (Include, Screenshot, Raw HTML) and missing Hugo default
  shortcodes (Highlight, Instagram, Param, Ref, Relref, Twitter, Vimeo, Youtube).
      - Restructured headings to ensure all sub-shortcodes are H3, removed block break tags (<br/>),
  and appended horizontal separators (---) after H2 sections.
This commit is contained in:
Michael
2026-06-06 19:26:33 +00:00
Unverified
parent d329fe9dfb
commit 835b118d1a
443 changed files with 33405 additions and 1220 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
layouts/partials/hero/background.html Normal file
View File

@@ -0,0 +1,102 @@
{{ $disableImageOptimization := site.Store.Get "disableImageOptimization" }}
{{ $useDefault := false }}
{{ $featured := "" }}
{{ $featuredURL := "" }}
{{ with .Params.featureimage }}
{{ if or (strings.HasPrefix . "http:") (strings.HasPrefix . "https:") }}
{{ if site.Params.hotlinkFeatureImage }}
{{ $featuredURL = . }}
{{ else }}
{{ $featured = resources.GetRemote . }}
{{ end }}
{{ else }}
{{ $featured = resources.Get . }}
{{ end }}
{{ end }}
{{ if not (or $featured $featuredURL) }}
{{ $images := .Resources.ByType "image" }}
{{ range slice "*background*" "*feature*" "*cover*" "*thumbnail*" }}
{{ if not $featured }}{{ $featured = $images.GetMatch . }}{{ end }}
{{ end }}
{{ end }}
{{ if not (or $featured $featuredURL) }}
{{ $default := site.Store.Get "defaultBackgroundImage" }}
{{ if $default.url }}
{{ $featuredURL = $default.url }}
{{ $useDefault = true }}
{{ else if $default.obj }}
{{ $featured = $default.obj }}
{{ $useDefault = true }}
{{ end }}
{{ end }}
{{/* generate image URL if not hotlink */}}
{{ if not $featuredURL }}
{{ with $featured }}
{{ $featuredURL = .RelPermalink }}
{{ if not (or $disableImageOptimization (eq .MediaType.SubType "svg")) }}
{{ $size := site.Store.Get "backgroundImageWidth" }}
{{ $featuredURL = (.Resize $size).RelPermalink }}
{{ end }}
{{ end }}
{{ end }}
{{ $scope := .Scratch.Get "scope" }}
{{ $shouldBlur := $.Params.layoutBackgroundBlur | default (or
(and ($.Site.Params.article.layoutBackgroundBlur | default true) (eq $scope "single"))
(and ($.Site.Params.list.layoutBackgroundBlur | default true) (eq $scope "list"))
(and ($.Site.Params.taxonomy.layoutBackgroundBlur | default true) (eq $scope "terms"))
(and ($.Site.Params.term.layoutBackgroundBlur | default true) (eq $scope "term"))
)
}}
{{ $shouldAddHeaderSpace := $.Params.layoutBackgroundHeaderSpace | default (or
(and ($.Site.Params.article.layoutBackgroundHeaderSpace | default true) (eq $scope "single"))
(and ($.Site.Params.list.layoutBackgroundHeaderSpace | default true) (eq $scope "list"))
(and ($.Site.Params.taxonomy.layoutBackgroundHeaderSpace | default true) (eq $scope "terms"))
(and ($.Site.Params.term.layoutBackgroundHeaderSpace | default true) (eq $scope "term"))
)
}}
{{- with $featuredURL -}}
{{ if $shouldAddHeaderSpace | default true }}
<div id="hero" class="h-[150px] md:h-[200px]"></div>
{{ end }}
<div class="fixed inset-x-0 top-0 h-[800px] single_hero_background nozoom">
{{ $style := "" }}
{{ $defaultPosition := cond $useDefault site.Params.imagePosition false }}
{{ with $.Params.imagePosition | default $defaultPosition }}
{{ $style = printf "object-position: %s;" . }}
{{ end }}
<img
id="background-image"
src="{{ . }}"
role="presentation"
loading="eager"
decoding="async"
fetchpriority="high"
class="absolute inset-0 w-full h-full object-cover"
{{ if $style }}style="{{ $style | safeCSS }}"{{ end }}>
<div
class="absolute inset-0 bg-gradient-to-t from-neutral dark:from-neutral-800 to-transparent mix-blend-normal"></div>
<div
class="absolute inset-0 opacity-60 bg-gradient-to-t from-neutral dark:from-neutral-800 to-neutral-100 dark:to-neutral-800 mix-blend-normal"></div>
</div>
{{ if $shouldBlur | default false }}
<div
id="background-blur"
class="fixed opacity-0 inset-x-0 top-0 h-full single_hero_background nozoom backdrop-blur-xl bg-neutral-100/75 dark:bg-neutral-800/60"></div>
{{ $backgroundBlur := resources.Get "js/background-blur.js" }}
{{ $backgroundBlur = $backgroundBlur | resources.Minify | resources.Fingerprint ($.Site.Params.fingerprintAlgorithm | default "sha512") }}
<script
type="text/javascript"
src="{{ $backgroundBlur.RelPermalink }}"
integrity="{{ $backgroundBlur.Data.Integrity }}"
data-blur-id="background-blur"
data-image-id="background-image"
data-image-url="{{ . }}"></script>
{{ end }}
{{- end -}}

63
layouts/partials/hero/basic.html Normal file
View File

@@ -0,0 +1,63 @@
{{ $disableImageOptimization := site.Store.Get "disableImageOptimization" }}
{{ $useDefault := false }}
{{ $featured := "" }}
{{ $featuredURL := "" }}
{{ with .Params.featureimage }}
{{ if or (strings.HasPrefix . "http:") (strings.HasPrefix . "https:") }}
{{ if site.Params.hotlinkFeatureImage }}
{{ $featuredURL = . }}
{{ else }}
{{ $featured = resources.GetRemote . }}
{{ end }}
{{ else }}
{{ $featured = resources.Get . }}
{{ end }}
{{ end }}
{{ if not (or $featured $featuredURL) }}
{{ $images := .Resources.ByType "image" }}
{{ range slice "*background*" "*feature*" "*cover*" "*thumbnail*" }}
{{ if not $featured }}{{ $featured = $images.GetMatch . }}{{ end }}
{{ end }}
{{ end }}
{{ if not (or $featured $featuredURL) }}
{{ $default := site.Store.Get "defaultBackgroundImage" }}
{{ if $default.url }}
{{ $featuredURL = $default.url }}
{{ $useDefault = true }}
{{ else if $default.obj }}
{{ $featured = $default.obj }}
{{ $useDefault = true }}
{{ end }}
{{ end }}
{{/* generate image URL if not hotlink */}}
{{ if not $featuredURL }}
{{ with $featured }}
{{ $featuredURL = .RelPermalink }}
{{ if not (or $disableImageOptimization (eq .MediaType.SubType "svg")) }}
{{ $size := site.Store.Get "backgroundImageWidth" }}
{{ $featuredURL = (.Resize $size).RelPermalink }}
{{ end }}
{{ end }}
{{ end }}
{{ with $featuredURL }}
{{ $style := "" }}
{{ $defaultPosition := cond $useDefault site.Params.imagePosition false }}
{{ with $.Params.imagePosition | default $defaultPosition }}
{{ $style = printf "object-position: %s;" . }}
{{ end }}
<div class="overflow-hidden h-36 md:h-56 lg:h-72">
<img
src="{{ . }}"
role="presentation"
loading="eager"
decoding="async"
fetchpriority="high"
class="w-full h-full nozoom object-cover"
{{ if $style }}style="{{ $style | safeCSS }}"{{ end }}>
</div>
{{ end }}

76
layouts/partials/hero/big.html Normal file
View File

@@ -0,0 +1,76 @@
{{ $disableImageOptimization := site.Store.Get "disableImageOptimization" }}
{{ $useDefault := false }}
{{ $featured := "" }}
{{ $featuredURL := "" }}
{{ with .Params.featureimage }}
{{ if or (strings.HasPrefix . "http:") (strings.HasPrefix . "https:") }}
{{ if site.Params.hotlinkFeatureImage }}
{{ $featuredURL = . }}
{{ else }}
{{ $featured = resources.GetRemote . }}
{{ end }}
{{ else }}
{{ $featured = resources.Get . }}
{{ end }}
{{ end }}
{{ if not (or $featured $featuredURL) }}
{{ $images := .Resources.ByType "image" }}
{{ range slice "*background*" "*feature*" "*cover*" "*thumbnail*" }}
{{ if not $featured }}{{ $featured = $images.GetMatch . }}{{ end }}
{{ end }}
{{ end }}
{{ if not (or $featured $featuredURL) }}
{{ $default := site.Store.Get "defaultBackgroundImage" }}
{{ if $default.url }}
{{ $featuredURL = $default.url }}
{{ $useDefault = true }}
{{ else if $default.obj }}
{{ $featured = $default.obj }}
{{ $useDefault = true }}
{{ end }}
{{ end }}
{{/* generate image URL if not hotlink */}}
{{ if not $featuredURL }}
{{ with $featured }}
{{ $featuredURL = .RelPermalink }}
{{ if not (or $disableImageOptimization (eq .MediaType.SubType "svg")) }}
{{ $size := site.Store.Get "backgroundImageWidth" }}
{{ $featuredURL = (.Resize $size).RelPermalink }}
{{ end }}
{{ end }}
{{ end }}
{{ $caption := "" }}
{{ if .Params.featureimagecaption }}
{{- $caption = .Params.featureimagecaption -}}
{{ end }}
{{- $alt := .Page.Title -}}
{{- with .Page.Params.alt }}{{ $alt = . }}{{ end -}}
{{ with $featuredURL }}
{{ $style := "" }}
{{ $defaultPosition := cond $useDefault site.Params.imagePosition false }}
{{ with $.Params.imagePosition | default $defaultPosition }}
{{ $style = printf "object-position: %s;" . }}
{{ end }}
<figure>
<img
src="{{ . }}"
alt="{{ $alt }}"
loading="eager"
decoding="async"
fetchpriority="high"
class="w-full rounded-lg single_hero_round nozoom"
{{ if $style }}style="{{ $style | safeCSS }}"{{ end }}>
{{ if $caption }}
<figcaption class="text-sm text-neutral-700 dark:text-neutral-400 hover:underline text-center">
{{ $caption | markdownify }}
</figcaption>
{{ end }}
</figure>
{{ end }}

138
layouts/partials/hero/thumbAndBackground.html Normal file
View File

@@ -0,0 +1,138 @@
{{ $disableImageOptimization := site.Store.Get "disableImageOptimization" }}
{{/* === Background === */}}
{{ $useDefault := false }}
{{ $images := .Resources.ByType "image" }}
{{ $background := $images.GetMatch "*background*" }}
{{ $backgroundURL := "" }}
{{ if not (or $background $backgroundURL) }}
{{ $default := site.Store.Get "defaultBackgroundImage" }}
{{ if $default.url }}
{{ $backgroundURL = $default.url }}
{{ $useDefault = true }}
{{ else if $default.obj }}
{{ $background = $default.obj }}
{{ $useDefault = true }}
{{ end }}
{{ end }}
{{ if not (or $background $backgroundURL) }}
{{ range slice "*cover*" "*thumbnail*" "*feature*" }}
{{ if not $background }}{{ $background = $images.GetMatch . }}{{ end }}
{{ end }}
{{ end }}
{{/* generate image URL if not hotlink */}}
{{ if not $backgroundURL }}
{{ with $background }}
{{ $backgroundURL = .RelPermalink }}
{{ if not (or $disableImageOptimization (eq .MediaType.SubType "svg")) }}
{{ $size := site.Store.Get "backgroundImageWidth" }}
{{ $backgroundURL = (.Resize $size).RelPermalink }}
{{ end }}
{{ end }}
{{ end }}
{{/* === Featured === */}}
{{ $featured := "" }}
{{ $featuredURL := "" }}
{{ with .Params.featureimage }}
{{ if or (strings.HasPrefix . "http:") (strings.HasPrefix . "https:") }}
{{ if site.Params.hotlinkFeatureImage }}
{{ $featuredURL = . }}
{{ else }}
{{ $featured = resources.GetRemote . }}
{{ end }}
{{ else }}
{{ $featured = resources.Get . }}
{{ end }}
{{ end }}
{{ if not (or $featured $featuredURL) }}
{{ $images := $.Resources.ByType "image" }}
{{ range slice "*feature*" "*cover*" "*thumbnail*" "*background*" }}
{{ if not $featured }}{{ $featured = $images.GetMatch . }}{{ end }}
{{ end }}
{{ end }}
{{ if not (or $featured $featuredURL) }}
{{ $default := site.Store.Get "defaultFeaturedImage" }}
{{ if $default.url }}
{{ $featuredURL = $default.url }}
{{ else if $default.obj }}
{{ $featured = $default.obj }}
{{ end }}
{{ end }}
{{/* generate image URL if not hotlink */}}
{{ if not $featuredURL }}
{{ with $featured }}
{{ $featuredURL = .RelPermalink }}
{{ if not (or $disableImageOptimization (eq .MediaType.SubType "svg")) }}
{{ $size := site.Store.Get "backgroundImageWidth" }}
{{ $featuredURL = (.Resize $size).RelPermalink }}
{{ end }}
{{ end }}
{{ end }}
{{ $scope := .Scratch.Get "scope" }}
{{ $shouldBlur := $.Params.layoutBackgroundBlur | default (or
(and ($.Site.Params.article.layoutBackgroundBlur | default true) (eq $scope "single"))
(and ($.Site.Params.list.layoutBackgroundBlur | default true) (eq $scope "list"))
(and ($.Site.Params.taxonomy.layoutBackgroundBlur | default true) (eq $scope "terms"))
(and ($.Site.Params.term.layoutBackgroundBlur | default true) (eq $scope "term"))
)
}}
{{ with $featuredURL }}
<div class="overflow-hidden rounded-md h-36 md:h-56 lg:h-72 nozoom">
<img
src="{{ . }}"
role="presentation"
loading="eager"
decoding="async"
fetchpriority="high"
class="w-full h-full nozoom object-cover"
{{ with $.Params.imagePositionFeature }}style="object-position: {{ . }};"{{ end }}>
</div>
{{ end }}
<div class="single_hero_background nozoom fixed inset-x-0 top-0 h-[800px]">
{{ with $backgroundURL }}
{{ $style := "" }}
{{ $defaultPosition := cond $useDefault site.Params.imagePosition false }}
{{ with $.Params.imagePosition | default $defaultPosition }}
{{ $style = printf "object-position: %s;" . }}
{{ end }}
<img
id="background-image-main"
src="{{ . }}"
role="presentation"
loading="eager"
decoding="async"
fetchpriority="high"
class="absolute inset-0 h-full w-full object-cover"
{{ if $style }}style="{{ $style | safeCSS }}"{{ end }}>
{{ end }}
<div
class="from-neutral absolute inset-0 bg-gradient-to-t to-transparent mix-blend-normal dark:from-neutral-800"></div>
<div
class="from-neutral to-neutral absolute inset-0 bg-gradient-to-t opacity-30 mix-blend-normal dark:from-neutral-800 dark:to-neutral-800 dark:opacity-60"></div>
</div>
{{ if $shouldBlur | default false }}
<div
id="background-blur"
class="fixed opacity-0 inset-x-0 top-0 h-full single_hero_background nozoom backdrop-blur-xl bg-neutral-100/75 dark:bg-neutral-800/60"></div>
{{ $backgroundBlur := resources.Get "js/background-blur.js" }}
{{ $backgroundBlur = $backgroundBlur | resources.Minify | resources.Fingerprint (.Site.Params.fingerprintAlgorithm | default "sha512") }}
<script
type="text/javascript"
src="{{ $backgroundBlur.RelPermalink }}"
integrity="{{ $backgroundBlur.Data.Integrity }}"
data-blur-id="background-blur"
data-image-id="background-image-main"
{{ with $background }}data-image-url="{{ .RelPermalink }}"{{ end }}></script>
{{ end }}