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

- 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.

layouts/_default/_markup/render-image.html

@@ -0,0 +1,114 @@
+{{- define "RenderImageSimple" -}}
+  {{- $imgObj := .imgObj -}}
+  {{- $src := .src -}}
+  {{- $alt := .alt -}}
+  <img
+    class="my-0 rounded-md"
+    loading="lazy"
+    decoding="async"
+    fetchpriority="low"
+    alt="{{ $alt }}"
+    src="{{ $src }}"
+    {{ with $imgObj -}}
+      {{ with $imgObj.Width }}width="{{ . }}"{{ end }}
+      {{ with $imgObj.Height }}height="{{ . }}"{{ end }}
+    {{- end }}>
+{{- end -}}
+
+{{- define "RenderImageResponsive" -}}
+  {{/* Responsive Image
+    The current setting sizes="(min-width: 768px) 50vw, 65vw" makes the iPhone 16 and 16 Pro
+    select a smaller image, while the iPhone 16 Pro Max selects a larger image.
+
+    Steps:
+    1. Check the media queries in the `sizes` property.
+    2. Find the first matching value. For example, on a mobile device with a CSS pixel width
+    of 390px and DPR = 3 (iPhone 13), given setting sizes="(min-width: 768px) 50vw, 100vw",
+    it matches the `100vw` option.
+    3. Calculate the optimal image size: 390 × 3 × 100% (100vw) = 1170.
+    4. Find the corresponding match in the `srcset`.
+
+    To make the browser select a smaller image on mobile devices
+    override the template and change the `sizes` property to "(min-width: 768px) 50vw, 30vw"
+
+    The sizes="auto" is valid only when loading="lazy".
+  */}}
+  {{- $imgObj := .imgObj -}}
+  {{- $alt := .alt -}}
+  {{- $originalWidth := $imgObj.Width -}}
+
+  {{- $img800 := $imgObj -}}
+  {{- $img1280 := $imgObj -}}
+  {{- if gt $originalWidth 800 -}}
+    {{- $img800 = $imgObj.Resize "800x" -}}
+  {{- end -}}
+  {{- if gt $originalWidth 1280 -}}
+    {{- $img1280 = $imgObj.Resize "1280x" -}}
+  {{- end -}}
+
+  {{- $srcset := printf "%s 800w, %s 1280w" $img800.RelPermalink $img1280.RelPermalink -}}
+
+
+  <img
+    class="my-0 rounded-md"
+    loading="lazy"
+    decoding="async"
+    fetchpriority="auto"
+    alt="{{ $alt }}"
+    {{ with $imgObj.Width }}width="{{ . }}"{{ end }}
+    {{ with $imgObj.Height }}height="{{ . }}"{{ end }}
+    src="{{ $img800.RelPermalink }}"
+    srcset="{{ $srcset }}"
+    sizes="(min-width: 768px) 50vw, 65vw"
+    data-zoom-src="{{ $imgObj.RelPermalink }}">
+{{- end -}}
+
+{{- define "RenderImageCaption" -}}
+  {{- with .caption -}}
+    <figcaption>{{ . | markdownify }}</figcaption>
+  {{- end -}}
+{{- end -}}
+
+{{- $disableImageOptimizationMD := .Page.Site.Params.disableImageOptimizationMD | default false -}}
+{{- $urlStr := .Destination | safeURL -}}
+{{- $url := urls.Parse $urlStr -}}
+{{- $altText := .Text -}}
+{{- $caption := .Title -}}
+{{- $isRemote := findRE "^(https?|data)" $url.Scheme -}}
+{{- $resource := "" -}}
+
+{{- if not $isRemote -}}
+  {{- $resource = or ($.Page.Resources.GetMatch $urlStr) (resources.Get $urlStr) -}}
+{{- end -}}
+
+
+<figure
+  {{- range $k, $v := .Attributes -}}
+    {{- if $v -}}
+      {{- printf " %s=%q" $k ($v | transform.HTMLEscape) | safeHTMLAttr -}}
+    {{- end -}}
+  {{- end -}}>
+  {{- if $isRemote -}}
+    {{- template "RenderImageSimple" (dict "imgObj" "" "src" $urlStr "alt" $altText) -}}
+  {{- else if $resource -}}
+    {{- $isSVG := eq $resource.MediaType.SubType "svg" -}}
+    {{- $shouldOptimize := and (not $disableImageOptimizationMD) (not $isSVG) -}}
+    {{- if $shouldOptimize -}}
+      {{- template "RenderImageResponsive" (dict "imgObj" $resource "alt" $altText) -}}
+    {{- else -}}
+      {{/* Not optimize image
+        If it is an SVG file, pass the permalink
+        Otherwise, pass the resource to allow width and height attributes
+      */}}
+      {{- if $isSVG -}}
+        {{- template "RenderImageSimple" (dict "imgObj" "" "src" $resource.RelPermalink "alt" $altText) -}}
+      {{- else -}}
+        {{- template "RenderImageSimple" (dict "imgObj" $resource "src" $resource.RelPermalink "alt" $altText) -}}
+      {{- end -}}
+    {{- end -}}
+  {{- else -}}
+    {{- template "RenderImageSimple" (dict "imgObj" "" "src" $urlStr "alt" $altText) -}}
+  {{- end -}}
+
+  {{- template "RenderImageCaption" (dict "caption" $caption) -}}
+</figure>