Skip to content

This is the multi-page printable view of this section. .

Return to the regular view of this page.

Oink Blog

OINK announcements, engineering stories, and implementation notes

1 - A gallery view for blog posts

Turn a blog section into a wall of linked covers, with three arrangements and captions that work on phones and keyboards.

Sometimes the cover is the quickest way to recognize a post. A travel journal, a collection of sketches, or a set of project notes can be easier to browse as images than as a column of titles.

OINK 1.4.0 adds a fourth blog view, gallery. Each post becomes a linked cover. The default arrangement joins images into rows; hovering or focusing a cover reveals its title and description. Clicking it opens the article.

Released in OINK 1.4.0

Gallery is part of the released theme. It keeps the ordinary blog article model and adds a cover-based way to browse the same posts.

Four ways to browse the same posts

The existing views answer different browsing needs. A table is useful when you know the date or title. Rows give summaries room to breathe. Cards put the cover and article metadata together. Gallery gives most of the space to the cover.

Blog view What the reader sees
list Horizontal entries with a thumbnail, metadata, and summary
cards A regular grid with 16:9 covers and article information
table Compact date, title, and tag rows
gallery Covers arranged by proportion, with titles and short descriptions

With the view switch enabled, all four forms use the same page of posts. Changing the view keeps the date order and current pagination slice. Readers can scan the covers, then switch to a table without losing their place in the archive. A standalone table still lists the whole section when switching is disabled.

Borrowing Expo’s layout

Expo already arranges images into a wall. Blog gallery reuses that row calculation and the same compact layout controls. The content still comes from ordinary blog pages: the featured image is the cover, the page title names it, and the description supplies the caption. There is no second album manifest to keep in sync.

The destination matters. An Expo tile opens an image viewer; a blog tile opens its article. A post with manual_link keeps that external destination. This makes the gallery useful as an index of writing, including short visual notes whose cover carries much of the story.

Inside Gallery, readers have three arrangements:

Arrangement Layout Captions
wall Rows with 6px gaps Revealed on hover or keyboard focus
seamless The same rows with no gaps Revealed on hover or keyboard focus
cards Masonry, placing each entry in the shortest column Always visible below the image

The gallery’s cards mode is the masonry arrangement, separate from the blog’s regular card view. A size slider changes the target tile size from 160 to 360 CSS pixels. Gallery remembers these choices separately from Expo, so changing a blog index does not rearrange an album on the next page.

Give captions room on a phone

A caption that only appears on hover is of little use on a touchscreen. On devices without a fine pointer and hover, Wall and Seamless put the text below the image. The layout reserves the tallest caption’s height for each row, so the following row cannot cover its links or text.

Very tall images need another adjustment. If their tiles preserve the exact source proportions on a narrow screen, the caption can shrink to a few characters per line. Below 500px of gallery width, we bound tile proportions more tightly. The full image remains visible inside its tile, with some empty space where necessary. That tradeoff keeps the text readable without cropping the cover.

Keyboard focus reveals the same caption as hover and adds an inset focus ring. The link has the article’s title as its accessible name. A post with no cover remains a clickable title tile; a failed image receives the same fallback. Without JavaScript, the page shows a responsive grid with visible captions and ordinary links.

Add these fields to a blog section’s _index.md front matter:

content/blog/_index.md
blog_index: gallery
blog_index_toggle: true
blog_index_size: 24
blog_gallery:
  mode: wall
  size: 240

blog_index chooses the initial view. blog_index_toggle lets readers cycle through all four views; set it to false to publish only the gallery. blog_index_size controls the number of posts per page, while blog_gallery.size controls the target tile size. They are independent.

For site defaults, put the same keys under params.ui:

hugo.yml
params:
  ui:
    blog_index: gallery
    blog_index_toggle: true
    blog_index_size: 24
    blog_gallery:
      mode: wall
      size: 240

A page or section cascade can override the site defaults. A blog_gallery block replaces the whole site block, so repeat both fields when you want to keep both settings. Existing bundled featured images and the images field continue to supply covers.

This configuration applies to the theme’s native blog section indexes; custom homepages and term templates must call the gallery partial explicitly.

Keeping the implementation small

The theme processes suitable large covers into previews within a 960 × 960 box, preserving their proportions. GIF covers use still previews. Images load lazily, including when a hidden view first becomes visible. Local covers require no remote image service or additional browser dependency.

Gallery has its own small runtime and reuses Expo’s geometry helper. It recalculates when a view becomes visible, the available width changes, fonts settle, or an image reveals its dimensions. These events matter more than the first screenshot: a layout can look correct initially and overlap after the sidebar moves or the reader changes views.

The checks compare article order across all four forms and across page boundaries. Browser coverage includes English and Chinese, desktop and touch, light and dark, keyboard navigation, missing covers, blocked images, and JavaScript being disabled. The parameter reference lives in the blog authoring guide, and the design decision records the ownership and content boundaries.

2 - Immersive reading on the Blog shell

Four front matter keys turn an ordinary Blog page into a reading-first layout with a full-bleed hero and an in-flow outline rail.

This page is rendered by the ordinary Blog shell. There is no special content type behind it. Four front matter keys change the presentation, and a section can set the same recipe once in a cascade:

featured_image: hero      # the image becomes a full-bleed opening
toc_style: flow           # a wider outline starts with the article
toc_taxonomies: false     # the rail carries the outline alone
sidebar_enabled: false

The hero

A page with a featured image can open with it. hero turns that image into a full-bleed backdrop across the top of the viewport, moves the title down to give it room, and masks the artwork away before the body begins. Because the shell paints it, the same presentation also works on a section index.

The page card, social preview, and Hero all use the same representative-image resolver. featured_image: banner keeps the framed alternative, while a page without a suitable image simply falls back to the normal opening.

The outline rail

toc_style: flow replaces the viewport-pinned outline with a wider rail in the content flow. It starts beside the article below the Hero and becomes sticky only after scrolling. The switch is independent of the image, so one section can keep a consistent outline even when some pages have no artwork.

toc_taxonomies: false removes the taxonomy clouds. If a page has neither an outline nor clouds, the empty rail is omitted completely.

What remains available

Everything below the opening is still a normal Blog article: date and reading time, tag badges, authors and profiles, the series strip, the description lead, sharing, annotation, sequential navigation, and comments. The Blog shell omits breadcrumbs by default; breadcrumb: true restores one for a page that needs its position in the tree to remain visible.

3 - Introducing the OINK implementation preview

OINK turns a directly customized Docsy codebase into a local-first, Hugo-only documentation theme with multilingual infrastructure and reusable content components.

Today we are publishing the OINK implementation preview: a directly evolved Docsy theme with one canonical product shell, a Hugo-only consumer build, local-first browser dependencies, a general multilingual framework, and a set of reusable content components drawn from PGSTY documentation sites.

This preview marks the implementation and documentation milestone ahead of the first tagged release and production Cloudflare Pages deployment.

Why OINK exists

Several mature documentation sites had independently copied the same Docsy layouts, navigation, search code, SCSS, JavaScript, and shortcodes. A common fix had to be repeated across repositories, while each site also carried a frontend toolchain and implicit network dependencies that made isolated builds harder than they needed to be.

OINK consolidates the genuinely reusable layer. Product matrices, portals, pricing pages, and other business-specific behavior stay in their own sites. The shared theme owns the documentation shell, browser runtimes, multilingual routing, accessibility behavior, and content-component contracts.

What changes

One product instead of a mode

OINK is not an optional skin. There is no oink.enabled flag, params.oink.* namespace, or parallel upstream-versus-brand template tree. The implementation in theme/ is the product.

That decision avoids two visual systems and two test matrices. Native Hugo settings and compatible Docsy parameters keep their established meanings.

Hugo-only consumer builds

A complete consuming site builds with:

hugo --gc --minify

Bootstrap, Font Awesome, fonts, search, diagrams, API documentation runtimes, and OINK components are committed with the theme. Node.js, npm, PostCSS, Autoprefixer, and CDN downloads are not consumer requirements.

Repository maintainers still use Node-based tools for tests and vendor refreshes. That maintenance toolchain is deliberately outside the public site-build contract.

Local-first browser behavior

The default starter serves its shell, fonts, icons, search, Mermaid, KaTeX, Markmap, Swagger UI, Redoc, Asciinema, ECharts, and Infographic dependencies from the generated site. Optional runtimes are selected per page and loaded at most once.

PlantUML and Diagrams.net do not receive public service defaults. A site must configure a controlled endpoint, use a pre-rendered result, or make an explicit remote-service choice.

Multilingual infrastructure

Language routing comes from Hugo’s language and translation objects. One configured language hides the selector. With two or more languages, a click advances by configured weight, while a short hover or keyboard focus opens the complete menu. If the current page lacks a translation, the selector goes to the target-language home page instead of a dead path.

The starter and documentation site use English as the primary language and Simplified Chinese as the second. Every page in the core docs and blog scope has a colocated .zh.md translation with stable explicit heading IDs.

Reusable components

OINK adds theme-owned Asciinema, ECharts, Infographic, document carousel, details, tabs, cards, navigation cards, document cards, and parameter components. They generate unique instance IDs and load their local assets only when used.

ECharts accepts structured JSON or YAML plus optional JavaScript callbacks referenced as $fn:name. Callback code runs only on pages that declare it.

What stays familiar

OINK retains Docsy’s content organization, front matter, documentation and blog sections, menus, taxonomies, print output, repository links, common shortcodes, diagrams, API reference features, and extension hooks. Existing sites can remove duplicated common implementations without rewriting ordinary Markdown.

The project also preserves Docsy’s Apache-2.0 history and attribution. A vendor manifest records pinned third-party sources, licenses, artifacts, and checksums.

Try the starter

Setup instructions updated on 2026-10-17

This article records the original implementation preview. Use Hugo Extended 0.168.0 for setup and validation today; the baseline advances with stable releases. Older-Hugo compatibility testing and adaptation are discontinued.

Install Git, Go 1.27 or newer, and Hugo Extended 0.168.0, then evaluate the official Starter:

git clone https://github.com/pgsty/oink-starter.git my-docs
cd my-docs
hugo server

Update older Starter workflow pins to the same Hugo baseline. Open the local English and Chinese pages, switch languages, search locally, change color mode, and visit the component examples. For an isolated environment, follow the offline archive installation guide.

Current validation

The implementation includes automated coverage for:

  • Hugo Extended 0.168.0 builds;
  • forbidden consumer Node/npm/PostCSS/Autoprefixer paths;
  • LTR, RTL, subpath, print, color-mode, and production assets;
  • hidden, click-to-cycle, hover-menu, translation-fallback, and RTL language behavior;
  • local per-page runtimes and repeated component instances;
  • ECharts structured options and callback integration;
  • an offline bilingual starter and offline release archive;
  • vendor licenses and checksums;
  • non-mutating migration rehearsals for SILO, PGSTY, SOW, and Pigsty.

The latest four-site rehearsal built temporary copies of all four sites cleanly.

What remains before release

Before tagging the first public release, we will finalize the module and package identities, apply the initial version across source tags, archives, and documentation, and connect the production Cloudflare Pages deployment to the pinned Hugo baseline.

4 - OINK implementation diary: from copied shells to one theme

A technical diary of the decisions, migrations, safety boundaries, tests, and documentation work behind the OINK implementation preview.

OINK began with an awkward observation: several production documentation sites looked related because they were related, but their common implementation lived as copied files. The visible result was consistent enough; the maintenance model was not.

This diary records the engineering decisions, migrations, and test constraints that turned those scattered site overrides into a single theme.

Locking the contract

The first useful work was subtraction. We wrote down what the product must be before choosing how to implement it:

  • an independent theme derived directly from Docsy;
  • one canonical shell, not a switchable skin;
  • Hugo Extended as the only consumer build dependency;
  • local-first delivery for every theme-owned browser asset;
  • multilingual behavior derived from Hugo rather than PGSTY domains;
  • reusable components in the theme, business semantics in the site;
  • preserved Docsy history, licenses, and upstream traceability.

This ruled out an attractive but costly shortcut: adding params.oink.enabled and leaving the old shell in place. A mode switch would have made every layout change, accessibility fix, and test support two products. Direct evolution made the intended design the only design.

Replacing the shell

The documentation, blog, and API-reference layouts were rebuilt around shared, small partials. The resulting shell includes:

  • global navigation and responsive sub-navigation;
  • a resizable, foldable sidebar;
  • local search and quick links;
  • language and color-mode controls;
  • breadcrumbs, table of contents, page metadata, and feedback;
  • a consistent footer and print layout.

The hard part was not drawing a navbar. It was preserving existing Docsy extension points while removing copied baseof.html files. Narrow hooks remain; site-wide shell duplication no longer has to be the normal customization path.

Removing the consumer toolchain

The original dependency chain assumed npm-provided Bootstrap and Font Awesome, and some paths invoked PostCSS. OINK moved the required sources and compiled artifacts into the theme and kept SCSS inside Hugo’s own asset pipeline.

Tests do more than check that hugo succeeds. Fixture traps fail if a consumer build tries to run Node.js, npm, PostCSS, or Autoprefixer, or if a template uses resources.GetRemote. LTR and RTL pages go through the same constraint.

This distinction matters: the repository still uses Node for its maintainer test harness. “Hugo-only” describes what a consuming site needs after it has a complete theme, not a ban on development tooling inside the theme repository.

Vendoring browser runtimes

The next layer was every dependency the browser might otherwise fetch: Bootstrap, Font Awesome, fonts, jQuery, Lunr, Mermaid, KaTeX, Markmap, Swagger UI, Redoc, Asciinema, ECharts, Infographic, and their supporting libraries.

Each selected artifact received a source, fixed version, license path, checksum, and update procedure in theme/VENDOR.json. Licenses live beside the vendored material. The manifest is validated against the actual files rather than treated as an aspirational inventory.

PlantUML and Diagrams.net forced a useful distinction. They are service-backed features, not merely JavaScript libraries. OINK refuses to invent a public endpoint: enabling one without a configured service fails the build.

Building the multilingual core

The previous language behavior was scattered across navigation and site-specific assumptions. The new core starts with Hugo’s configured languages, .Translations, and .AllTranslations.

The presentation is deliberately stable: one language hides the selector; two or more use the same icon button. Clicking advances by configured weight, while a short hover or keyboard focus opens the complete language menu.

A missing translation falls back to the target-language home page. Language labels use each language’s own name. The same objects drive lang, direction, canonical, hreflang, and Open Graph locale metadata, so the visible selector cannot drift from SEO output.

The tests construct every state with an RTL current language as well as normal LTR cases. Native links and disclosure controls keep keyboard behavior predictable.

Promoting components

Asciinema, ECharts, Infographic, document carousel, details, tabs, cards, and parameter rendering had already proved valuable in PGSTY sites. The work was to turn them from copies into product APIs:

  • normalize parameter names and defaults;
  • generate unique IDs from page identity and shortcode ordinal;
  • load each runtime once per page and omit it from unused pages;
  • preserve subpath URLs;
  • support repeated identical instances;
  • provide print, dark-mode, mobile, keyboard, and reduced-motion behavior;
  • retain compatible aliases for imported content.

Product matrices and other business widgets did not move. Reuse is not measured by the number of repositories containing a copy; it requires a stable, business-neutral contract.

Supporting ECharts callbacks

ECharts callbacks are legitimate chart options that JSON and YAML cannot express. Existing pages use them for tooltip formatting, label formatting, and data-dependent colors. Treating those callbacks as a separate migration exception added configuration without creating a sandbox.

The shortcode therefore keeps one direct contract:

  1. content supplies JSON or YAML, which Hugo parses and safely serializes;
  2. an optional fenced JavaScript block declares callbacks;
  3. $fn:name values reconnect those callbacks after the options are parsed;
  4. authors review executable code under the same trust model as inline HTML and other custom integrations.

Tests cover repeated identical charts, invalid CSS lengths, structured options, and callback registration.

Creating the starter and archive

A contract is easier to trust when the smallest example demonstrates it. The starter contains bilingual home, docs, blog, and component pages; local search; dark mode; diagrams; API documentation; and the new components. It has no package.json and no site workflow.

The offline packager combines theme/, starter/, licenses, the upstream record, and migration guidance, excluding generated output and dependency caches. It writes a sidecar SHA-256 file and refuses to overwrite an existing artifact.

The acceptance test copies the starter and theme to a temporary directory, empties caches, blocks HTTP/HTTPS and Go proxies, builds with Hugo, and examines HTML and CSS for third-party subresources.

Rehearsing four migrations

SILO, PGSTY, SOW, and Pigsty provided the reality check. The rehearsal tool copies each workspace instead of modifying it, removes only classified common overrides, applies a local theme replacement, forbids network and frontend tools, and runs the production build.

The latest rehearsal removed 20 common overrides from SILO, PGSTY, and SOW and 24 from Pigsty. Pigsty retained its three business matrix shortcodes and existing ECharts callbacks. All temporary copies built cleanly, producing 1,095, 16, 128, and 2,473 HTML files respectively.

Turning the sample into OINK docs

The inherited docsy.dev site was valuable as a regression corpus, but it described only Docsy. The documentation phase did four things:

  1. made English primary and Simplified Chinese second; a later shell review removed French from the demonstration site;
  2. translated every core documentation and blog source into a colocated .zh.md page;
  3. preserved English heading IDs explicitly in every Chinese heading;
  4. added the OINK product guide, announcement, and this implementation diary.

Before translation, we established a terminology and typography guide. A checker then verifies source/translation pairs, heading counts, explicit Chinese IDs, and rendered English/Chinese heading-ID equality.

Historical Docsy release posts remain faithful translations. Their npm-era instructions are historical context, while the OINK architecture and migration guides state the current Hugo-only product contract.

What testing changed

Several tests changed the design rather than merely blessing it:

  • subpath fixtures forced every local component URL through Hugo URL handling;
  • repeated-instance tests replaced content hashes with page-and-ordinal IDs;
  • offline browser checks exposed implicit runtime requests;
  • RTL language matrices prevented a selector implementation that only worked for the starter’s two LTR languages;
  • ECharts callback fixtures kept callback registration and structured options interoperable;
  • migration rehearsals preserved site-specific partials that a blanket layouts/ deletion would have removed.

Remaining work

Before the first tagged release, we will finalize the public repository, module and package identities, and connect the Cloudflare Pages project to build from the source branch.

Production migrations will proceed one site at a time on dedicated branches, with preview deployments, visual regression checks, and rollback artifacts.

Lessons

  • Write the product boundary before moving files.
  • Verify local-first delivery at both build time and browser runtime.
  • Keep configuration focused on user choices rather than internal implementation branches.
  • Check stable links, code fidelity, typography, and rendered structure alongside translated prose.
  • Consolidate shared mechanics in the theme while keeping business-specific widgets in their sites.

The result is one theme that can be built, tested, translated, and upgraded as a coherent product.