From b169c2b37835ec89c19b1b3b8d731907d11e7e08 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 29 Apr 2026 22:24:15 +0000
Subject: [PATCH] docs: switch to permanent v0.x.x versioning
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The repo's go.mod declares `module github.com/arty2/onion` (no /vN
suffix). Per Go's semantic-import-versioning rule
(https://go.dev/ref/mod#major-version-suffixes), any tag with major
version ≥ 2 is unconsumable via the Go module proxy unless the path
includes a matching /v2, /v3, … suffix. That made every v2.x and
v3.x tag effectively dead — `hugo mod get github.com/arty2/onion@v3.1.0`
fails with a module-path-mismatch error.

Two fixes are possible: add /v3 to go.mod (and bump it on every
future major), or stay below v2.0 and live in v0.x.x permanently.
v0 and v1 are exempt from the suffix rule; the Go ecosystem has
ample precedent for indefinite v0 (golang.org/x/…, many libraries).
For a Hugo theme — which doesn't ship API stability the way a
library does — permanent v0 is the right tradeoff.

This commit is docs-only; the destructive cleanup (deleting the 9
existing tags + Releases, tagging v0.1.0) lands as a follow-up
once this PR is merged so the v0.1.0 tag points at a commit that
already contains CHANGELOG.md.

What changed:

* CHANGELOG.md (new) — verbatim salvage of the 9 retired Releases'
  body text, newest-first, with a header explaining the
  renumbering. v2.3.0's detailed pre-AI → AI-orchestrated changelog
  is preserved in full; the terse early entries (v1.0, v2.0) are
  preserved as historical placeholders.
* RELEASING.md — "## Versioning" rewritten. v0.X.0 covers both
  features and breaking changes (since in v0, breaking changes
  don't bump a major). v0.X.Y is patch. First release is v0.1.0.
  Cites the Go module-suffix rule and points at CHANGELOG.md for
  retired tags.
* README.md — "As a Hugo Module" install instructions pin v0.1.0
  by default; the boilerplate `hugo mod get` line at the bottom
  swapped from `vX.Y.Z` to `v0.X.Y`. Pointer added from the
  Development section to CHANGELOG.md.
---
 CHANGELOG.md | 189 +++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md    |   6 +-
 RELEASING.md |  20 +++---
 3 files changed, 202 insertions(+), 13 deletions(-)
 create mode 100644 CHANGELOG.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..e95fa41
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,189 @@
+# Changelog
+
+This file preserves the release-note bodies of the pre-policy v1 / v2
+/ v3 tags that were retired when the project switched to permanent
+v0.x.x versioning (see [RELEASING.md](./RELEASING.md)). The tags and
+GitHub Releases themselves were deleted to sidestep Go's
+[major-version-suffix rule](https://go.dev/ref/mod#major-version-suffixes),
+which makes any `v2+` tag unconsumable via `hugo mod get` unless the
+`go.mod` module path includes a matching `/v2` (or `/v3`, …) suffix.
+The first release under the new policy is `v0.1.0`, functionally
+equivalent to what was briefly tagged as `v3.2.0`.
+
+The bodies below are quoted verbatim from the original GitHub
+Releases.
+
+
+## v3.2.0 — 2026-04-29
+
+What's Changed:
+
+- add print.css as print-media stylesheet by @Arty2 in #6
+- docs: document articles-list / articles-filter / image modifiers by @Arty2 in #4
+- forge-content: multi-platform content shortcode replacing github-content by @Arty2 in #7
+- polish: localStorage safety, scroll perf, a11y, dead code, modernize CSS by @Arty2 in #5
+
+Full Changelog: v3.1.0…v3.2.0
+
+
+## v3.1.0 — 2026-04-26
+
+What's Changed: restructured CSS styles.
+
+Full Changelog: v3.0.1…v3.1.0
+
+
+## v3.0.1 — 2026-04-26
+
+What's Changed:
+
+- forge-meta partial + harden github-content against shortcode injection by @Arty2 in #2
+
+Full Changelog: v3.0.0…v3.0.1
+
+
+## v3.0.0 — 2026-04-26
+
+What's Changed: major codebase restructuring with Claude Opus.
+
+- Hugo compatibility and cleanup
+- Automated tests
+- Metadata and module infrastructure
+- CSS restructuring and modernization
+
+Full Changelog: v2.3.0…v3.0.0
+
+
+## v2.3.0 — 2026-04-26
+
+Incorporated previous manual changes from https://heracl.es with
+orchestration from Claude Sonnet.
+
+Full Changelog: v2.2…v2.3.0
+
+### New
+
+**Dailymotion shortcode** (`layouts/shortcodes/dailymotion.html`) —
+embed videos via `{{< dailymotion id="…" >}}`. Supports `player`,
+`mute`, `loading`, `ratio`, `width`, and `class` params. When
+`Shortcodes.Dailymotion.Disable` is set in site config, renders a
+plain fallback link instead of an iframe.
+
+**Explicit color scheme classes** — `.scheme--light` and
+`.scheme--dark` classes can now be applied to any element (not just
+through `prefers-color-scheme`). Each scheme sets `--blend-mode`
+(multiply/screen) and `--blend-filter` (none/invert) for image
+blending. Light theme color changed to a blue-tinted white
+(`221, 238, 255`); dark accent changed from blue to magenta
+(`205, 35, 185`).
+
+**`CustomCSS` front matter** — per-page inline `<style>` injected
+via `Params.CustomCSS`.
+
+**`featuredClass` Store variable** — partials can set
+`.Store "featuredClass" "cover"` to render featured images as
+full-bleed covers instead of thumbnails. Single pages use this by
+default. The `featured-img` partial now supports `cover`,
+`featured`, and `thumbnail` front matter params with correct
+priority per class.
+
+**RSS `<category>` elements** — each feed item now emits
+`<category domain="types">` and `<category domain="tags">` entries.
+Items with `Sitemap.Disable: true` are excluded from feeds.
+
+**`.no-taxa` and `.no-types` modifier classes** — use on
+`.articles-list` to hide all taxa or just type taxa.
+
+### Improvements
+
+**Font stacks expanded** — `--font-mono`: adds Source Code Pro,
+SF Mono, Roboto Mono, DejaVu Mono. `--font-serif`: adds Source
+Serif, New York, Cambria, Roboto Serif, DejaVu Serif. `--font-sans`:
+corrected from `Alegreya Sansa` to `Alegreya Sans`; adds Source
+Sans, SF Pro, Candara, Verdana, Roboto, DejaVu Sans. Default body
+font changed from sans-serif to serif.
+
+**Code block scroll shadows** — `<pre>` blocks use a pure-CSS
+radial-gradient technique to show scroll-shadow indicators at
+left/right overflow edges. The border and language label moved
+from `<code>` to the `<pre>` wrapper; language label repositioned
+to top-left.
+
+**Video embeds rewritten** — `.video` now uses `aspect-ratio: 16/9`
++ flexbox instead of the old `padding-bottom: 56.25%` hack. When a
+video embed is disabled, the fallback shows a full-area link with a
+CSS `▶` play icon.
+
+**RSS XSL reader view redesigned** — language switcher nav with
+`aria-current` added. Items now display type/tag categories and a
+formatted date. Date formatting done via an XSL named template. RSS
+"about" text links to a "feed reader" article.
+
+**Search index and UI (`askolonion.js`)** — `section` field renamed
+to `types` in the JSON index. Search result order now matches
+article listing: type → tags → title → summary → date. Arrow keys
+`←`/`→` added as navigation shortcuts (Right = go to first result,
+Left = return to search input).
+
+**Language switcher accessibility** — `<nav>` gains `aria-label`
+(new i18n key `languages-available`) and items use
+`aria-current="page"`, `rel="alternate"`, and `hreflang` instead of
+a `.active` class.
+
+**Image rendering (`render-image.html`)** — now checks both page
+resources and global resources. GIF files are never resized
+(avoids broken animations). Self-closing `<img />` for XML
+compatibility. `<figure>` / `<figcaption>` wrapping moved outside
+the resource lookup so it applies in all cases. Extra attributes
+passed via an `Attributes` dict are forwarded to the `<img>`.
+
+**Copyright renders Markdown** — `site.Copyright` in footer and
+RSS now passes through `RenderString`, so Markdown links work.
+
+**`Scratch` → `Store` in templates** — `index.json` and
+`single.html` migrated from the deprecated `.Scratch` to `.Store`.
+
+### Fixes
+
+- `render-link.html`: removed the `TrimLeft "0123456789"` workaround
+  for links starting with digits; replaced with proper `urls.Parse`
+  / `IsAbs` check. External links get `data-src="external"` instead
+  of `target="_blank"`.
+- `single.html`: fixed `Resources.Match` → `.Resources.Match` (was
+  accessing global scope incorrectly).
+- `articles-filter.html`: taxonomy page lookup uses `path.Join`
+  instead of `printf "/%s"`.
+- `.articles-list.no-tags` now targets `.tag` elements, not `.tags`
+  containers.
+- `articles-list` hover no longer fires on articles without an
+  `<a href>`.
+- `content-visibility: auto` disabled on article list items (was
+  forcing `overflow: hidden` and clipping content).
+- `meta.html`: `license` i18n key corrected to `post-license`.
+- Disqus comments block removed from `single.html` (was broken
+  without `disqusShortname`).
+- Greek translation: `filter-reset` changed from "Όλα" to "Άπαντα";
+  RSS about text fixed typo and updated wording.
+
+
+## v2.2 — 2026-04-18
+
+Pre-AI.
+
+
+## v2.1 — 2020-09-25
+
+- Typographic scale and various UI refinements.
+- `{{< github-content >}}` shortcode to build pages from GitHub
+  readmes.
+- YAML custom param `github`, to add repository details to a page.
+
+
+## v2.0 — 2020-09-16
+
+(no release notes)
+
+
+## v1.0 — 2020-09-16
+
+(no release notes)
diff --git a/README.md b/README.md
index ce04107..8453551 100644
--- a/README.md
+++ b/README.md
@@ -219,7 +219,7 @@ The theme works on **Hugo ≥ 0.154** (Extended is strongly recommended for WebP
 
 ```sh
 hugo mod init github.com/you/your-site
-hugo mod get github.com/arty2/onion
+hugo mod get github.com/arty2/onion@v0.1.0
 ```
 
 Then in `hugo.toml`:
@@ -228,7 +228,7 @@ Then in `hugo.toml`:
 theme = ["github.com/arty2/onion"]
 ```
 
-Update later with `hugo mod get -u github.com/arty2/onion`.
+Update to a newer minor with `hugo mod get -u github.com/arty2/onion@v0.X.Y`. Pinning a minor (rather than `@latest`) gives reproducible builds; see [RELEASING.md](./RELEASING.md) for the v0.x.x versioning policy.
 
 ### As a Git submodule
 
@@ -367,7 +367,7 @@ Prefetch/prerender is delegated to the browser via [Speculation Rules](https://d
 - CI (`.github/workflows/build.yml`) builds the example site on every push against two Hugo versions (a pinned reproducible one and `latest`) and runs `html-validate` plus a deprecation grep against the output.
 - Minimum supported Hugo: **0.154.0** (for the `try` statement used in `forge-meta`). Bumped here whenever the theme relies on a newer template feature.
 
-Releases follow [`RELEASING.md`](./RELEASING.md): tag `vX.Y.Z`, push the tag, and the Go module proxy serves it as `hugo mod get github.com/arty2/onion@vX.Y.Z`.
+Releases follow [`RELEASING.md`](./RELEASING.md): tag `v0.X.Y`, push the tag, and the Go module proxy serves it as `hugo mod get github.com/arty2/onion@v0.X.Y`. See [`CHANGELOG.md`](./CHANGELOG.md) for the catalogue of pre-policy v1/v2/v3 releases retired during the move to permanent v0.x.x versioning.
 
 
 * * *
diff --git a/RELEASING.md b/RELEASING.md
index e73cd60..db14842 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -6,29 +6,29 @@ Hugo Module consumers fetch the theme via the Go module proxy:
 hugo mod get github.com/arty2/onion@latest
 ```
 
-`@latest` resolves to the highest semver tag in the repo. To cut a release:
+`@latest` resolves to the highest semver tag. To cut a release:
 
 ```sh
-git tag vX.Y.Z
-git push origin vX.Y.Z
+git tag v0.X.Y
+git push origin v0.X.Y
 ```
 
 The Go proxy picks it up within a few minutes. Users then upgrade with:
 
 ```sh
-hugo mod get -u github.com/arty2/onion@vX.Y.Z
+hugo mod get -u github.com/arty2/onion@v0.X.Y
 ```
 
 ## Versioning
 
-We follow [SemVer](https://semver.org/):
+This theme stays on `v0.x.x` indefinitely. Per Go's [semantic-import-versioning rule](https://go.dev/ref/mod#major-version-suffixes), any tag with major version ≥ 2 requires a `/v2` (or `/v3`, …) suffix in the `go.mod` module path AND in every consumer's `theme = ["…"]` line. Staying on v0 sidesteps that without giving up granular versioning of changes — and is well-precedented in the Go ecosystem (`golang.org/x/…`, many widely-used libraries).
 
-- **MAJOR** — breaking changes to template params, partials a downstream
-  site might override, CSS class names, or removed shortcodes.
-- **MINOR** — new shortcodes, partials, params, or i18n strings.
-- **PATCH** — bug fixes, doc updates, asset tweaks, CI changes.
+Within `v0`:
 
-The first release should be `v1.0.0`.
+- **MINOR** (`v0.X.0`) — new shortcodes, partials, params, i18n strings, OR breaking changes to template params, partials a downstream site might override, CSS class names, or removed shortcodes. (In v0, breaking changes don't bump a major; they bump MINOR. Downstream sites should pin a minor version they've tested.)
+- **PATCH** (`v0.X.Y`) — bug fixes, doc updates, asset tweaks, CI changes, dependency bumps.
+
+The first release under this policy is `v0.1.0`. The retired pre-policy tags (v1.0, v2.x, v3.x) are catalogued in [CHANGELOG.md](./CHANGELOG.md).
 
 ## Pre-release checklist