This is the multi-page printable view of this section. .
Oink Blog
- 1: A gallery view for blog posts
- 2: Immersive reading on the Blog shell
- 3: Introducing the OINK implementation preview
- 4: OINK implementation diary: from copied shells to one theme
1 - A gallery view for blog posts
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.
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.
Enable it for a section
Add these fields to a blog section’s _index.md front matter:
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:
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
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:
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
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:
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
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:
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.
Read next
4 - OINK implementation diary: from copied shells to one theme
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:
- content supplies JSON or YAML, which Hugo parses and safely serializes;
- an optional fenced JavaScript block declares callbacks;
$fn:namevalues reconnect those callbacks after the options are parsed;- 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:
- made English primary and Simplified Chinese second; a later shell review removed French from the demonstration site;
- translated every core documentation and blog source into a colocated
.zh.mdpage; - preserved English heading IDs explicitly in every Chinese heading;
- 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.