Cards
{.cards} to a link list to create navigation cards. Use the shortcode for icons, badges, or images.Cards provide related links. Each card has a linked title and a sentence. The grid adapts to the container width. Use cards for section landing pages, reading recommendations, or a few related entry points. Use paragraphs for prose and a gallery for image collections.
Optional presentation
Use {.cards .td-cards-list} for a single-column resource list with shared dividers, or cards variant="list" for the full form. OINK 1.4.0 supports these opt-in variants; compare the examples. The default remains a responsive grid.
Shortest form
Add {.cards} to a link list to make a card grid. The link becomes the title.
Text after — becomes the description.
- Get started — Start with OINK Starter, preview locally, then replace the site details with your own.
- Authoring — How pages are organized and which front matter keys exist.
- Customization — Navigation, search, branding, languages.
The whole card is clickable. There is no columns parameter.
The number of columns follows the container width and decreases to one on narrow screens.
Title-only cards
The description is optional. Put one link on each line and {.cards} after the list.
Loose lists and longer descriptions
If a sentence is insufficient, use a loose list. Put the link and description in separate paragraphs, with blank lines between items.
The title appears above the description. {.cards} must immediately follow the last paragraph, with no blank line between them.
-
Every page parameter is defined here exactly once: type, default, accepted values, and the page that explains it.
-
Site parameters grouped by feature, each row linking back to the guide that explains it.
Icons and badges
Link lists do not support icons, badges, images, or descriptions with multiple paragraphs. Use the cards / card shortcode for these features.
icon takes exactly one Font Awesome class pair. badge is plain text.
Use OINK Starter and establish a local preview before customizing.
A release card from release_url and date, plus a checksums block for download assets.
Site-wide shortcuts and focus order.
An invalid Font Awesome class pair warns and is removed in ordinary previews. Review the warning and rendered fallback before publication.
Markdown bodies
A card body uses page-level Markdown, including inline code, emphasis, links, and lists.
Parameters such as title and badge are plain text. They are not parsed as Markdown.
hugo mod get github.com/pgsty/oink. The recommended way; upgrading is one
version line.
No Go installation needed:
git submodule add- the theme lands in
themes/oink
A card without link renders as a bold title and produces no link.
Cards with images
image uses the same resolution order as : page resource → current section resource → global resource in assets/ → static path /images/… → remote URL.
Local resources include their intrinsic size, which prevents layout changes during loading.
With image, provide exactly one alternative-text source. Use image_alt="…" for informative images or decorative=true for decorative images.
If you provide both, the theme warns and keeps the alt text. If you provide neither, it warns and makes the image decorative.
Review the warning and rendered fallback before publication.
Sidebar, article, table of contents — each can be turned off on its own.
A decorative cover: decorative=true emits an empty alt and screen readers skip it.
Card images do not take part in image zoom — the whole card is already a link.
Automatic cards on section pages
A section landing page (_index.md) needs no manual card list. The theme generates cards from each child page’s title, description, and icon.
This site enables section cards globally in hugo.yml:
A section can override this setting in its front matter. Use cascade to apply the setting to the whole subtree:
Automatic and manual cards share the td-content-card styles. Only their data source differs.
Do not manually list child pages on a section page. The list can become inconsistent with the sidebar.
Use manual cards for other sets, such as external links or recommendations from other sections.
Configuration defines these keys.
Which form to use
| What you want | Which form |
|---|---|
| A grid of links with one-sentence descriptions | {.cards} link list |
| Icons, badges, images | cards / card shortcode |
| Lists, code or several paragraphs in the description | cards / card shortcode |
| A card with no link | cards / card shortcode |
| This section’s child pages | nothing at all — section_index: cards |
The native form stays readable as a link list on GitHub. Shortcodes do not. Use the native form when it supports your content.
Output
| Output | Shape |
|---|---|
| HTML | Native form: <ul class="cards">. Shortcode form: <div class="td-content-cards"> with one <article class="td-content-card"> each. Both are pure CSS grids and load no script |
| The native form stacks; the shortcode form collapses to two columns; in both, a card avoids breaking across pages | |
| Markdown | The native form keeps the link list; the shortcode form emits - [Title](link) (badge) — description |
| RSS | The same markup as HTML — a readable list of links without site CSS |
Parameter reference
The native form:
card parameters (cards also accepts an optional variant="list"):
There is no cols, columns, accent, desc, or color parameter.
Unknown parameters warn and are ignored.
Limits
{.cards}supports only unordered lists. It has no effect on ordered lists.{.cards}must immediately follow the list. A blank line or indentation inside a list item silently removes the marker. The build succeeds, but the result stays a list. Check this line first if no card grid appears.- A
cardmust be insidecards. Alone or inside another shortcode, it warns and is skipped. - The grid adapts to its container. Its column count cannot be configured.
Only automatic section cards accept a count, through
params.ui.section_index_columns. - If a description exceeds two lines, use a paragraph or a callout.
Related
- Fields — also has a native form and a shortcode form
- Galleries — a grid of images
- Badges — inline status labels
- Organizing content — sections, weights and landing pages
- Configuration —
section_indexand friends