bdeshi/khosra
0
0
Fork 0
Code Issues Pull Requests Releases Activity

add the gallery shortcode and the seam it needed

Browse Source 
A feature now learns which bundle is rendering: render.Bundle puts an Origin —
the bundle's directory plus the rooted fs.FS — on the parse context, and
render.OriginFrom reads it back. Available while parsing, not while rendering,
which decides where a feature does its filesystem work: goldmark hands the
context to a block parser and not to a node renderer, so gallery gathers its
filenames at parse time and carries them on the node.

Reads stay inside the site root because Origin passes the fs.FS rather than a
path to join (ADR-0031).

Fragment{Args, Items} lands with it (ADR-0037), so figure's template now reads
.Args.src. Authored arguments and engine-gathered items stay in separate fields:
a src argument beside a src the engine found would otherwise silently pick one.

A gallery is pictures beside the bundle, in filename order, skipping
subdirectories and anything a browser cannot show. Filename order is what makes
the sparse numeric-prefix convention work without numbers in URLs (ADR-0016).

New latent row: the reference theme's images carry no width/height and a
gallery's carry no alt, which is below the output floor conventions.md states.
Nothing can supply either yet — dimensions need the image read, and a filename is
not alt text. Queue 13 computes dimensions and brings structured items with it.
This commit is contained in:
bdeshi
2026-08-01 02:23:35 +06:00
parent dbc617698c
commit 6c9a34a8fd
8 changed files with 199 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/theme-contract.md
+17 -5
View File
@@ -76,15 +76,27 @@ block; site-supplied strings wait for the settings cascade (`ideas/deferred-deci
## Shortcode fragments
`templates/shortcodes.html` holds one named template per shortcode, and that is where a shortcode's markup
lives — the engine parses the call and supplies its arguments, never any HTML (ADR-0036).
lives — the engine parses the call and supplies its data, never any HTML (ADR-0036).
Every fragment receives the same two fields (ADR-0037):
| Field | Contents |
|---|---|
| `.Args` | the call's `key="value"` pairs, exactly as the author wrote them |
| `.Items` | a list the *engine* gathered, empty unless that shortcode gathers one |
| Shortcode | Template | Receives |
|---|---|---|
| `{{< figure src="…" alt="…" caption="…" >}}` | `figure` | `.src`, `.alt`, `.caption` — every argument as written, escaped on output |
| `{{< figure src="…" alt="…" caption="…" >}}` | `figure` | `.Args.src`, `.Args.alt`, `.Args.caption` |
| `{{< gallery >}}` | `gallery` | `.Items` — the picture filenames beside the bundle, in filename order |
Arguments arrive as strings and are escaped by `html/template` like any other data, which is what keeps an
author's text out of the markup. A call whose template is missing renders nothing and logs; it never fails
the page.
Authored and engine-supplied data are kept apart so a `src` argument can never be confused with a `src` the
engine found. Arguments are escaped by `html/template` like any other data, in whichever context the
template puts them — which is what keeps an author's text out of the markup. A call whose template is
missing renders nothing and logs; it never fails the page.
A gallery entry is a bare filename, relative to the bundle, so a template writes it straight into `src`. It
carries no alt text or dimensions, because nothing in a filename supplies either.
The set is overlaid the same way as the page kinds: a site's `templates/shortcodes.html` is parsed after
the embedded one, so redefining `figure` replaces it and any fragment left alone is inherited. Argument