Releases and downloads
OINK stores release metadata in two local places: a page’s front matter
release_url identifies its GitHub release, and data/download/<key>.yaml
records installation instructions. Release cards, asset tables, download blocks,
and index pages derive their links from those records without contacting GitHub
at build time.
Its front matter holds a release_url (OINK v0.4.0), and the card, asset
table and download block below are really rendered. The checksums and asset
filenames are fabricated. The URLs are derived locally from the repository and
tag. Their target files do not exist in any real release.
Do not use these hashes to verify anything.
Components and where the facts come from
| What you want | What renders it | Facts come from |
|---|---|---|
| A version summary card (tag, date, archives, repo) | release-card |
The page’s release_url |
| A checksum asset table | The checksums fence / release-assets |
sha*sum lines in the body |
| A multi-channel download block | download |
data/download/<key>.yaml |
| A chronological release index | layout: releases |
Each page’s release_url, or its title |
The page owns the release facts
One front matter key contains the release record. It is the GitHub release URL for an exact tag:
The URL supplies the owner, project, and tag. The page’s date supplies the
date. An invalid exact-tag GitHub release URL warns and skips the release block.
The 0.5
release map (product / version / repo / tag / date / prev / checksums) and
its string shorthand are removed. A page that still uses either gets a warning
that names release_url.
Put a parameterless shortcode where you want the summary. The call accepts no release facts:
The card shows four locally derived links: the release, both source archives, and the repository. Checksum files belong in the asset table below a note, and comparisons live on GitHub.
The release index page
A section can switch to the release index layout. It lists every regular page in the section, newest first by page date. Within one day, the tag’s version breaks ties. It uses SemVer precedence with a deterministic fallback for non-SemVer tags:
If release_url parses, the entry shows project tag, such as oink v0.4.0,
above the page description. A page without that URL keeps its own title. A
plain note between releases is therefore an ordinary entry and causes no warning. The 0.5
release_products filter and release_group_by_product grouping are gone;
Using either warns.
This site’s Releases currently uses the ordinary blog list.
Switch to layout: releases when a strict chronology is wanted.
Checksum assets
The checksums fence is the native form of a checksum table, holding the
verbatim output of a sha*sum command:
| File | Checksum | |
|---|---|---|
| oink-0.4.0-linux-amd64.tar.gz Linuxamd64SHA-256 | 1e2f4c8a…e7c4 |
|
| oink-0.4.0-darwin-arm64.tar.gz macOSarm64SHA-256 | 7b3d9e0c…8250 |
Only two line shapes are accepted: <hex><two spaces><filename> and
<hex><space>*<filename>. Blank lines and lines starting with # are ignored.
The hash length determines the algorithm (MD5 / SHA-1 / SHA-256 / SHA-512), and
each block holds a single algorithm. Malformed lines log a warning with the
line number and are skipped. Each filename must be a single path segment;
package type, OS, and architecture badges are inferred from the filename when
recognized.
If the page has release_url front matter, the base for asset links is derived
as https://github.com/<repo>/releases/download/<tag>/. A page without release
facts must set base= explicitly. Having both is an error.
release-assets is the shortcode form of the same parser and renderer. It adds
one parameter that the fence lacks, src=. Use it for a checksum file stored
as a page resource or global asset. src and inner content are mutually
exclusive. group="auto" groups by platform and architecture:
.rpm
| File | Checksum | |
|---|---|---|
| oink-0.4.0-1.el9.x86_64.rpm Linuxamd64SHA-256 | 5a0c7d1e…7db6 |
|
| oink-0.4.0-1.el9.aarch64.rpm Linuxarm64SHA-256 | c93f16a8…0ea8 |
HTML shows a truncated hash. The accessible name and copied text retain the full value. The copy button uses a local runtime loaded on demand. With JavaScript disabled it is still a complete linked table. Print expands the full hash without controls, and Markdown and RSS emit a pipe table of full hashes.
Download channel data
Installation instructions belong to the product rather than one release. Store
them in data/download/<key>.yaml. This site’s real record is
data/download/prd5.yaml:
The record has five top-level fields: version, repo, tag, published,
and channels (any unknown top-level key logs a warning and skips the record).
version may be omitted here and supplied by the site’s params.version
instead.
Each channel:
Two rules:
- Localization resolves by suffix:
<field>_<exact language>→<field>_<base language>→<field>. A Chinese site resolvestitle_zh_cn, thentitle_zh, thentitle. camelCase aliases are not accepted. - Only a pinned channel’s
urlandsteps[].codeinterpolate${version}and${tag}. A rolling channel refuses interpolation, so a stable install command is never bound to one version. Titles and notes never interpolate.
Rendering the download block
download takes exactly one positional parameter, the data key:
Install script
The rolling channel deliberately contains no version interpolation.
Source archive
Release assets
| File | Checksum | |
|---|---|---|
| oink-0.4.0.tar.gz SHA-256 | aaaaaaaa…aaaa |
HTML renders a row of anchor chips and one section per channel. Code steps reuse the enhanced code block and its on-demand copy runtime. A checksum channel reuses the asset table above. Print statically expands the same content, Markdown emits the titles, source fences and full hashes, and RSS omits the component.
Before you create the tag and upload assets, mark the record unpublished:
Rolling channels keep working. Pinned channels become an unclickable “pending release” state, omit the pinned commands, and disable asset links and copy controls. After the tag and assets resolve, change the publication state. Do not write a guessed link in the prose.
The same record can supply a landing page’s download section. No second version
model is required. See
Home and landing pages.
How this relates to blog release notes
The two have different jobs:
- A release note in the blog (this site keeps them in
content/blog/release/) explains what changed, how to upgrade, and what breaks. Its front matter carriesrelease_url, and arelease-cardcan sit at the top. For writing instructions, see Blog posts. - Download data identifies the channel, command, and hash. It is separate from the version number. An upgrade changes one place.
For a release, follow this order: update version in data/download/<key>.yaml → write a
new content/blog/release/<version>.md with its release_url → set
published to true after the tag and assets are in place.
Verify
- Build with visible diagnostics:
hugo --printPathWarnings. A malformed hash line, mixed algorithms, a missingbaseand a misspelled channel field all produce warnings that need review. - On the page: the card’s tag and date match the repository, and every asset row opens a real download URL.
- Check hashes against the actual artifacts manually. The component only displays them. It verifies nothing.
- Confirm the hashes are complete in non-HTML output:
- Test with
published: falsefirst. Set it totrueonly after the tag and assets exist. Test each language and a subpath deployment.
Related
- Blog posts — where release notes live and how they are ordered
- Code Blocks — code rendering and copying inside download steps
- Home and landing pages — the landing
downloadsection - Configuration —
params.versionand the related site parameters - Upgrade — how a consuming site tracks theme versions