wip(web): load swagger and mermaid only where used, single jQuery

Author: lgarciaog

web/SITES_MERGE_PLAYBOOK.md

@@ -481,6 +481,23 @@ Also removed here: leftover unconditional `needs: []` on the web jobs (from
 an earlier iteration — independence from the product pipeline is opt-in via
 `BUILD_GL_PAGES`, step 16's CI note).
 
+### 24. Docs asset diet: conditional swagger/mermaid, one jQuery
+
+sg-doc loaded swagger-ui (two JS bundles + CSS, twice) and mermaid on every
+docs page; exactly one page uses swagger (`sg-swaggerui` shortcode on the API
+reference) and none currently use mermaid. The doc header/footer partials now
+gate those assets with `.HasShortcode`. The docs' jQuery 3.3.1 was replaced by
+the main site's 3.4.1 (one jQuery site-wide; the theme's 3.3.1 file is
+unreferenced). Also fixed the `sg-swaggerui` shortcode (project override): it
+built the spec URL as `BaseURL + "/sg-swagger.yaml"`, which yields the
+protocol-relative `//sg-swagger.yaml` when baseURL is `/` (artifact preview) —
+now `relURL`, correct for every baseURL shape.
+
+Found while verifying, NOT fixed here: the vendored swagger-ui is a 3.x-era
+build and rejects the operator's OpenAPI **3.1** spec ("Unable to render this
+definition") — **the live stackgres.io API reference page is broken the same
+way**. Fix = vendor swagger-ui v5 (supports 3.1). Recorded under known gaps.
+
 ## Verified
 
 - `hugo` builds with **0 errors** (379 pages)
@@ -522,5 +539,11 @@ an earlier iteration — independence from the product pipeline is opt-in via
   that only resolve via the live site's redirect-to-docs-home fallback.
   Converting them to `relurl`/markdown links is a mechanical follow-up pass.
 - **RSS/sitemap dedup** between the three sections was not reviewed.
+- **Operator API reference doesn't render** (pre-existing, also broken on
+  live stackgres.io): the operator's swagger is OpenAPI 3.1, the vendored
+  swagger-ui bundle only supports ≤3.0. Upgrade to swagger-ui v5 (drop-in:
+  `swagger-ui-bundle.js`, `swagger-ui-standalone-preset.js`,
+  `swagger-ui.css` as project static overrides; the shortcode API is
+  unchanged in v5).
 - **CI/deploy.** Each source repo had its own pipeline; the umbrella needs one
   (build + link-check + deploy).

web/layouts/partials/doc/footer.html

@@ -67,14 +67,18 @@
     <script src="{{"js/learn.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}"></script>
     <script src="{{"js/hugo-learn.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}"></script>
 
+    {{ if .HasShortcode "mermaid" }}
     <link href="{{"mermaid/mermaid.css" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" rel="stylesheet" />
     <script src="{{"mermaid/mermaid.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}"></script>
     <script>
         mermaid.initialize({ startOnLoad: true });
     </script>
+    {{ end }}
+    {{ if .HasShortcode "sg-swaggerui" }}
     <link href="{{"css/swagger-ui.css" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" rel="stylesheet" />
     <script src="{{"js/swagger-ui-bundle.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}"></script>
     <script src="{{"js/swagger-ui-standalone-preset.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}"></script>
+    {{ end }}
 
     {{ partial "custom-footer.html" . }}
   </body>

web/layouts/partials/doc/header.html

@@ -23,9 +23,9 @@
     {{with .Site.Params.themeVariant}}
       <link href="{{(printf "css/theme-%s.css" .) | relURL}}{{ if $assetBusting }}?{{ now.Unix }}{{ end }}" rel="stylesheet">
     {{end}}
-    <link href="{{ "css/swagger-ui.css" | relURL }}" rel="stylesheet" type="text/css">
+    {{ if .HasShortcode "sg-swaggerui" }}<link href="{{ "css/swagger-ui.css" | relURL }}" rel="stylesheet" type="text/css">{{ end }}
 
-    <script src="{{"js/jquery-3.3.1.min.js"| relURL}}{{ if $assetBusting }}?{{ now.Unix }}{{ end }}"></script>
+    <script src="{{"js/jquery-3.4.1.min.js"| relURL}}{{ if $assetBusting }}?{{ now.Unix }}{{ end }}"></script>
 
     <style>
       :root #header + #content > #left > #rlblock_left{

web/layouts/shortcodes/sg-swaggerui.html

@@ -0,0 +1,16 @@
+<div id="ohpen_swagger_ui"></div>
+<script>
+window.onload = function() {
+  const ui = SwaggerUIBundle({
+    url: "{{ "sg-swagger.yaml" | relURL }}",
+    dom_id: '#ohpen_swagger_ui',
+    presets: [
+      SwaggerUIBundle.presets.apis,
+      SwaggerUIStandalonePreset
+    ],
+    docExpansion: "list"
+  })
+
+  window.ui = ui
+}
+</script>