Gallery of example decks, rendered by go-slides at build time

.github/workflows/docs.yml

@@ -68,6 +68,34 @@ jobs:
           echo "version=${version}" >> "$GITHUB_OUTPUT"
           echo "slides ${slides}: documentation version ${version}"
 
+      # The gallery: the decks of go-slides/slides' examples/, rendered by
+      # go-slides itself (tools/gallery builds the slides command from the same
+      # checkout), as data/gallery.json and static/gallery/. The ref is
+      # params.gallery.ref in hugo.yaml.
+      - name: Gallery ref
+        id: gallery
+        run: echo "ref=$(hugo config --format json | jq -r '.params.gallery.ref')" >> "$GITHUB_OUTPUT"
+
+      - name: Check out the examples
+        uses: actions/checkout@v7
+        with:
+          repository: go-slides/slides
+          ref: ${{ steps.gallery.outputs.ref }}
+          path: slides-src
+
+      - uses: actions/setup-go@v7
+        with:
+          go-version: "1.27.2"
+          cache: false
+
+      - name: Build the gallery
+        env:
+          GOWORK: "off"
+        working-directory: tools/gallery
+        run: |
+          go test ./...
+          go run . -src ../../slides-src -out ../..
+
       # Each page's creation (first commit, followed across renames) and its
       # author, for the page history at its foot (params.page.history).
       - name: Page history

.gitignore

@@ -6,3 +6,9 @@
 
 # Written by themes/hextra/scripts/page-history.sh before each build (CI and local).
 /data/pagehistory.json
+
+# Written by tools/gallery before each build (CI and local): the gallery's data
+# and its thumbnails, sources and archives.
+/data/gallery.json
+/static/gallery/
+/slides-src/

README.md

@@ -41,6 +41,8 @@ against that release (flags from its `slides -h`).
 | `assets/css/custom.css` | the brand indigo as Hextra's primary colour, with its contrast measured |
 | `themes/hextra` | submodule: tannevaled/hextra at tag v0.16.0 |
 | `branding` | submodule: [go-slides/brand](https://github.com/go-slides/brand) |
+| `tools/gallery` | a Go program (stdlib only, with tests) that renders the gallery: it reads go-slides/slides' `examples/`, renders each deck's first slide with the slides command, and writes `data/gallery.json` and `static/gallery/` (both ignored by git) |
+| `layouts/_shortcodes/gallery.html` | the gallery page's cards, from `data/gallery.json` |
 | `scripts/publish-version.sh` | puts one build into a `gh-pages` checkout and rewrites `versions.json`, `latest` and the root redirect |
 
 ## Working locally
@@ -49,10 +51,14 @@ against that release (flags from its `slides -h`).
 git clone --recurse-submodules https://github.com/go-slides/docs.git
 cd docs
 mkdir -p data && sh themes/hextra/scripts/page-history.sh > data/pagehistory.json
+git clone https://github.com/go-slides/slides ../slides      # the gallery's decks
+(cd tools/gallery && go run . -src ../../../slides -out ../..)   # Go 1.27.2 or later
 hugo server --baseURL http://localhost:1313/docs/main/
 ```
 
-Hugo 0.146 or later; no Python, no Node.
+Hugo 0.146 or later; no Python, no Node. The gallery page fails the build when
+`data/gallery.json` is missing, which is the `go run` line above. CI does it
+before every build, from the ref `params.gallery.ref` names.
 
 ## Publication
 

assets/css/custom.css

@@ -29,6 +29,22 @@
  * stays on screen at the end of the navbar. */
 .fs-version-select .hextra-nav-menu-items { left: auto !important; right: 0; transform: none !important; }
 
+/* The gallery (layouts/_shortcodes/gallery.html): a card per deck. */
+.gallery { display: grid; gap: 1.5rem; grid-template-columns: repeat(auto-fill, minmax(min(100%, 22rem), 1fr)); margin-top: 1.5rem; }
+.gallery-card { border: 1px solid #d1d5db; border-radius: 0.75rem; padding: 0.75rem; min-width: 0; }
+.dark .gallery-card { border-color: #374151; }
+.gallery-thumb img { width: 100%; height: auto; aspect-ratio: 16 / 9; object-fit: cover; border-radius: 0.5rem; border: 1px solid #e5e7eb; }
+.gallery-card h3 { margin: 0.75rem 0 0; font-size: 1.1rem; }
+.gallery-card p { margin: 0.4rem 0 0; }
+.gallery-meta { font-size: 0.8rem; opacity: 0.7; }
+.gallery-actions { display: flex; flex-wrap: wrap; gap: 0.5rem 1rem; align-items: center; }
+.gallery-open { background: #4F46E5; color: #fff; padding: 0.25rem 0.75rem; border-radius: 0.375rem; font-weight: 600; text-decoration: none; }
+.gallery-open:hover { background: #4338ca; }
+.gallery-note { font-size: 0.85rem; }
+.gallery-card details { margin-top: 0.6rem; }
+.gallery-card summary { cursor: pointer; font-weight: 600; }
+.gallery-card pre { max-height: 24rem; overflow: auto; }
+
 /* The outdated-version banner (layouts/_partials/custom/content-begin.html). */
 .nd-outdated { margin-top: 1rem; padding: 0.75rem 1rem; border-radius: 0.5rem;
   border: 1px solid #f59e0b; background: #fffbeb; color: #78350f; }

content/en/_index.md

@@ -50,6 +50,7 @@ here that is done by Go libraries.
 ## Pages
 
 - [Getting started]({{< relref "getting-started" >}})
+- [Gallery]({{< relref "gallery" >}}): twelve example decks, to open in the playground
 - [Marp compatibility]({{< relref "marp" >}})
 - [Templates]({{< relref "templates" >}})
 - [Kinds]({{< relref "kinds" >}})

content/en/gallery.md

@@ -0,0 +1,24 @@
+---
+title: "Gallery"
+weight: 12
+description: "Twelve small decks, each showing one thing well: themes, kinds, templates, HCL, math, images, code, emoji, transitions and a complete talk. Open any of them in the playground."
+tags: [gallery, examples]
+---
+
+Twelve small decks from the
+[`examples/`](https://github.com/go-slides/slides/tree/main/examples) folder of
+go-slides, each showing one thing well. The thumbnails are the first slide of
+each deck, rendered by go-slides itself when this site is built; CI builds every
+deck to HTML and PDF, so none of them breaks.
+
+**Open in the playground** loads the deck in your browser, in a link that sends
+nothing to any server. A deck that has files besides `deck.md` (a kinds file,
+included parts, images) cannot travel in a link: download its **.zip**, and
+import it with the playground's file panel, or unzip it and build it with
+`slides build --allow-local-files deck.md`.
+
+The pictures are original SVGs of the go-slides authors, released under
+[CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/), and the decks
+that use them say so.
+
+{{< gallery >}}

hugo.yaml

@@ -92,6 +92,12 @@ params:
   # being written, and say so.
   slides:
     version: "v0.9.0"
+  # The ref of go-slides/slides whose examples/ the gallery shows, and from
+  # which tools/gallery builds the slides command that renders the thumbnails
+  # (the CI reads it here). "main" until a release has an examples/ folder;
+  # then the release's tag, so that the gallery matches the pages.
+  gallery:
+    ref: "main"
   versions:
     # The version selector shows "main" with the development icon.
     development: "main"

layouts/_shortcodes/gallery.html

@@ -0,0 +1,39 @@
+{{- /*
+  The gallery of example decks, from data/gallery.json and static/gallery/,
+  which tools/gallery writes before every build (CI and local).
+*/ -}}
+{{- $items := hugo.Data.gallery -}}
+{{- if not $items -}}
+  {{- errorf "gallery: data/gallery.json is missing. Run `go run ./tools/gallery -src ../slides` from the repository's root (see README.md)" -}}
+{{- end -}}
+<div class="gallery">
+{{- range $items }}
+  <article class="gallery-card" id="{{ .name }}">
+    <a class="gallery-thumb" href="{{ .thumbnail | relURL }}">
+      <img src="{{ .thumbnail | relURL }}" alt="The first slide of “{{ .title }}”" width="640" height="360" loading="lazy">
+    </a>
+    <h3><a href="#{{ .name }}">{{ .title }}</a></h3>
+    <p class="gallery-meta">{{ .slides }} slides</p>
+    <p>{{ .description }}</p>
+    <p class="gallery-actions">
+      {{- if .playground }}
+      <a class="gallery-open" href="{{ .playground | safeURL }}">Open in the playground</a>
+      {{- end }}
+      {{- if .zip }}
+      <a class="gallery-open" href="{{ .zip | relURL }}">Download the .zip</a>
+      {{- end }}
+      <a href="{{ .repo }}">Source on GitHub</a>
+    </p>
+    {{- if .zip }}
+    <p class="gallery-note">This deck has files besides <code>deck.md</code>
+      ({{ range $i, $f := .files }}{{ if $i }}, {{ end }}<code>{{ $f }}</code>{{ end }}),
+      so it cannot travel in a link: unzip it and run <code>slides build --allow-local-files deck.md</code>,
+      or import the .zip with the playground's <em>Import</em>.</p>
+    {{- end }}
+    <details>
+      <summary>deck.md</summary>
+      {{ highlight (readFile .source) "markdown" "" }}
+    </details>
+  </article>
+{{- end }}
+</div>

tools/gallery/go.mod

@@ -0,0 +1,3 @@
+module github.com/go-slides/docs/tools/gallery
+
+go 1.27.2