# OINK

> A local-first, Hugo-only theme for technical documentation

## Site index

- [Home page](https://oink.pgsty.com/index.md)
- [navigation.json](https://oink.pgsty.com/navigation.json)
- [Docs](https://oink.pgsty.com/docs/index.md): OINK is a local-first Hugo documentation framework — components stay readable in Markdown, assets ship with the theme, multilingual sites work out of the box, and one source serves readers and agents.
- [Book](https://oink.pgsty.com/book/index.md): A practical tutorial for creating clear, beautiful, and maintainable technical content with OINK.
- [Case](https://oink.pgsty.com/case/index.md): Fifteen real sites show how OINK scales from a two-page utility to a multilingual documentation estate and three books.
- [Blog](https://oink.pgsty.com/blog/index.md): OINK engineering stories, immersive guides, and release notes

## Documentation index

- [Introduction](https://oink.pgsty.com/docs/about/index.md): A local-first Hugo documentation framework evolved from Docsy. Its components stay readable in Markdown, its assets ship with the theme, and fifteen production sites exercise it.
  - [Highlights](https://oink.pgsty.com/docs/about/features/index.md): What separates OINK from an ordinary Hugo theme, one item at a time, each linking to the guide that covers it.
  - [Cases](https://oink.pgsty.com/docs/about/showcase/index.md): Find the OINK production case closest to your documentation, book, landing page, or interactive tool.
  - [License](https://oink.pgsty.com/docs/about/license/index.md): Which licence applies to which layer — Apache-2.0 for the theme, CC BY 4.0 for the documentation, and their own terms for every third-party runtime shipped with the theme.
- [Get started](https://oink.pgsty.com/docs/start/index.md): Start from the official OINK Starter, establish a working local baseline, then customize content, language, brand, integrations, and deployment in that order.
  - [OINK Starter](https://oink.pgsty.com/docs/start/starter/index.md): Turn the official starter into your project site, one controlled layer at a time — identity, languages, home page, content, navigation, brand, integrations, and deployment.
  - [Repository tour](https://oink.pgsty.com/docs/start/anatomy/index.md): A file-level map of oink-starter — what owns identity, languages, home, content, navigation, brand, deployment, and the pinned theme.
  - [From scratch](https://oink.pgsty.com/docs/start/from-scratch/index.md): Build a minimal OINK site in an empty directory, and weigh the four install methods — Module, submodule, offline archive, pinned clone.
- [Authoring](https://oink.pgsty.com/docs/write/index.md): Writing documentation pages, blog posts, books, release pages and API references — what a page looks like, and how content is organized.
  - [Writing pages](https://oink.pgsty.com/docs/write/pages/index.md): Creating a documentation page — where the file goes, what the front matter says, why heading anchors are written by hand, how links and images work, and what appears at the end of a page on its own.
  - [Organizing content](https://oink.pgsty.com/docs/write/organize/index.md): The directory structure is the sidebar tree — `_index.md` and weight, section index styles, icons and folding, hiding pages, and putting documentation at any path.
  - [Page parameters](https://oink.pgsty.com/docs/write/frontmatter/index.md): The full front matter table — every page key the theme actually reads, grouped by sidebar, shell, search, output, page end, Book, landing and release pages.
  - [Blog posts](https://oink.pgsty.com/docs/write/blog/index.md): Setting up a blog section — directory conventions, a post's front matter, featured images, the year-grouped list page, and RSS.
  - [Books](https://oink.pgsty.com/docs/write/book/index.md): Turn a directory tree into a book with `type: book`: chapter numbering, numbered figures and tables, cross-references, generated indexes and whole-book print.
  - [Releases and downloads](https://oink.pgsty.com/docs/write/releases/index.md): Record versions, tags, archive links, checksums and install commands as local facts, then let release cards, asset tables, download blocks and index pages derive from that one record.
  - [API reference](https://oink.pgsty.com/docs/write/openapi/index.md): Put an OpenAPI specification on the site and render it as a browsable API reference with the bundled Swagger UI or Redoc, without touching a CDN.
- [Components](https://oink.pgsty.com/docs/components/index.md): Every component available for writing, one page each, examples from the simplest upwards, with the parameter table at the end.
  - [Callouts](https://oink.pgsty.com/docs/components/callout/index.md): Write notes, warnings and collapsible asides — with colour, icon and title — as `> [!NOTE]` blockquotes, no shortcode involved.
  - [Images](https://oink.pgsty.com/docs/components/image/index.md): Plain Markdown image syntax plus one attribute line gives you captions, sizing, zoom, links, numbering and Hugo image processing.
  - [Code Blocks](https://oink.pgsty.com/docs/components/code/index.md): A plain Markdown fence plus one attribute line gives you a filename title, exact copy, line numbers, highlighting, wrapping, folding and linkable lines.
  - [Tabs](https://oink.pgsty.com/docs/components/tabs/index.md): A `{tab=}` attribute on adjacent fences or tables makes a tab set; add a group and it becomes linkable, synchronized and remembered.
  - [Tables](https://oink.pgsty.com/docs/components/table/index.md): A plain GFM table plus one attribute line becomes a captioned table, a compatibility matrix, a field list, a numbered table or a tab set; wide tables scroll on their own.
  - [Fields](https://oink.pgsty.com/docs/components/fields/index.md): A plain table plus `{.fields}` documents configuration keys, command flags and API fields — name, type, default and description each in place, readable on a narrow screen, every entry individually linkable.
  - [Steps](https://oink.pgsty.com/docs/components/steps/index.md): An ordered list plus `{.steps}` becomes a numbered procedure with dots and a connecting rule; switch to the steps shortcode when each step needs a heading in the table of contents.
  - [Cards](https://oink.pgsty.com/docs/components/cards/index.md): A link list plus `{.cards}` lays out a grid of navigation cards; switch to the shortcode when you need icons, badges or images.
  - [FileTree](https://oink.pgsty.com/docs/components/filetree/index.md): A `filetree` fence draws an annotated directory structure — aligned comment column, per-entry icons, collapsible directories, a draggable split.
  - [Math](https://oink.pgsty.com/docs/components/math/index.md): Inline and display mathematics with KaTeX, rendered at build time — the reader downloads no script.
  - [Mermaid](https://oink.pgsty.com/docs/components/mermaid/index.md): A `mermaid` fence turns text into flowcharts, sequence diagrams, Gantt charts, class diagrams and state diagrams — rendered locally, theme-aware, diff-friendly.
  - [PlantUML](https://oink.pgsty.com/docs/components/plantuml/index.md): A `plantuml` fence writes sequence, class, component, activity and use-case diagrams; rendering requires a PlantUML server you configure yourself.
  - [Markmap](https://oink.pgsty.com/docs/components/markmap/index.md): A `markmap` fence turns a Markdown outline into an expandable, zoomable mind map — and the source stays a readable outline.
  - [Draw.io](https://oink.pgsty.com/docs/components/drawio/index.md): Put a `.drawio.svg` that carries an editable copy on the page as an ordinary image; hovering gives the reader a button that opens the Draw.io editor.
  - [ECharts](https://oink.pgsty.com/docs/components/echarts/index.md): Write ECharts options as YAML or JSON in an `echarts` fence; Hugo validates them at build time and the browser draws a theme-aware chart with the local ECharts.
  - [Infographic](https://oink.pgsty.com/docs/components/infographic/index.md): An `infographic` fence picks an AntV template and renders a title plus a list of items as a flow, timeline, funnel, grid or hierarchy.
  - [Gallery](https://oink.pgsty.com/docs/components/gallery/index.md): A `gallery` fence arranges related screenshots in a responsive grid, each with an optional description or link, reusing the page's image zoom dialog.
  - [Badge](https://oink.pgsty.com/docs/components/badge/index.md): Put a semantic status label next to a feature name, a version or a table cell — five tones, no custom colours.
  - [Kbd](https://oink.pgsty.com/docs/components/kbd/index.md): Write shortcuts with `kbd` — one shortcode, a list of key names, a semantic key sequence that stays readable in print and in Markdown output.
  - [Includes](https://oink.pgsty.com/docs/components/include/index.md): Pull an external file in with include, print a site parameter with param, and write a note that reaches no output at all with comment.
  - [Asciinema](https://oink.pgsty.com/docs/components/asciinema/index.md): Put a .cast terminal recording on the page — the text stays selectable text, and the player ships with the theme rather than coming from a CDN.
- [Customization](https://oink.pgsty.com/docs/customize/index.md): Site-level configuration — brand, navigation, layout, search, languages, versions, print and agent output.
  - [Configuration](https://oink.pgsty.com/docs/customize/config/index.md): The one place site parameters are defined — every key the theme reads, with its type, default and the guide that covers it.
  - [Brand and appearance](https://oink.pgsty.com/docs/customize/brand/index.md): Replace the site name, logo, favicon, accent colour, light and dark palettes and fonts, using configuration and two SCSS entry points.
  - [Home and landing pages](https://oink.pgsty.com/docs/customize/home/index.md): Assemble a home page from one local YAML file — hero, cards, capability panels, timeline, pricing, case studies, downloads. Any page can become a landing page with the same sections.
  - [Navigation and menus](https://oink.pgsty.com/docs/customize/navigation/index.md): Configure the navbar menu and its dropdowns, the section switcher, breadcrumbs, page actions, the pager and the footer links.
  - [Layouts and page types](https://oink.pgsty.com/docs/customize/layout/index.md): Let `type` decide which shell a page uses, then adjust sidebar width and icons, outline depth, section index style and page width.
  - [Search](https://oink.pgsty.com/docs/customize/search/index.md): Turn on local search, control index size and result ranking, and make CJK queries land.
  - [Command palette](https://oink.pgsty.com/docs/customize/panel/index.md): One dialog carrying page search, page actions and site commands — how to open it, what it groups, and how to add commands of your own.
  - [Keyboard navigation](https://oink.pgsty.com/docs/customize/keyboard/index.md): Every single-key shortcut, when each stands down for typing, and how to turn them off per site or per page.
  - [Languages](https://oink.pgsty.com/docs/customize/i18n/index.md): Add a language, keep translations side by side, configure menus and interface strings per language, and align heading anchors across languages.
  - [Versions](https://oink.pgsty.com/docs/customize/versions/index.md): Configure the version switcher and the archive banner, and choose how several versions are laid out across domains.
  - [Taxonomies](https://oink.pgsty.com/docs/customize/taxonomy/index.md): Give pages a second index that cuts across the directory tree with tags and categories — term pages, filter chips, the rail cloud and the navbar panel are all automatic.
  - [Repository links](https://oink.pgsty.com/docs/customize/repository/index.md): Wire "edit this page", "open an issue" and "view history" to your repository, and show the last-modified line, contributors and the feedback widget at the page end.
  - [Print](https://oink.pgsty.com/docs/customize/print/index.md): A single page goes to the browser's Cmd/Ctrl+P; a whole section becomes one continuous document through the print output format.
  - [AI-agent support](https://oink.pgsty.com/docs/customize/agents/index.md): Give every page a `.md` twin, the site root an `llms.txt`, and the reader a way to hand the current page to ChatGPT or Claude.
- [Operations](https://oink.pgsty.com/docs/admin/index.md): Running the site from a laptop to production — local preview, deployment, comments, analytics and SEO, upgrades and troubleshooting.
  - [Local preview](https://oink.pgsty.com/docs/admin/preview/index.md): Preview changes with hugo server, build a deployable public/ with hugo --panicOnWarning, and need neither Node nor a CDN.
  - [Deploy](https://oink.pgsty.com/docs/admin/deploy/index.md): Publish public/ to GitHub Pages, Cloudflare Pages or any static host — matching baseURL, Content Security Policy, the acceptance checklist and rollback.
  - [Comments](https://oink.pgsty.com/docs/admin/comments/index.md): Wire GitHub Discussions into a comment section at the bottom of a page with giscus — on site-wide, off per page, following light and dark.
  - [Analytics and SEO](https://oink.pgsty.com/docs/admin/analytics/index.md): Connect an analytics service (or none), and pair up the canonical, hreflang, social cards, sitemap and robots the theme already generates.
  - [Upgrade](https://oink.pgsty.com/docs/admin/upgrade/index.md): Move to a new theme version, convert 0.4 shortcodes to current native forms with the migration toolkit, migrate from Docsy, and roll back safely.
  - [Troubleshooting](https://oink.pgsty.com/docs/admin/troubleshooting/index.md): Symptom → cause → fix for the four fault classes — build, language, search, platform — plus the checks a site can run for itself.
- [Design](https://oink.pgsty.com/docs/design/index.md): OINK maintainer contracts, accepted decisions, dated research, and proposals in one canonical bilingual section.
  - [Architecture](https://oink.pgsty.com/docs/design/architecture/index.md): Repository assembly, configuration, diagnostics, localization, output, performance, security, CSS, accessibility, and release-state boundaries.
  - [Diagnostics](https://oink.pgsty.com/docs/design/decisions/diagnostics/index.md): Invalid author input warns and degrades safely during preview; --panicOnWarning restores a hard publication gate.
  - [Goldmark attributes](https://oink.pgsty.com/docs/design/research/goldmark-attributes/index.md): Reproducible findings for lists, images, tables, passthrough blocks, fences, callouts, and nested containers on Hugo 0.160.1 and 0.164.0.
  - [Knowledge graph](https://oink.pgsty.com/docs/design/proposals/knowledge-graph/index.md): A draft three-stage design for deriving backlinks and local or global graph views from ordinary Hugo links.
  - [Components](https://oink.pgsty.com/docs/design/components/index.md): The maintainer contract for OINK authoring primitives, validation, Book and release behavior, and output degradation.
  - [Configuration](https://oink.pgsty.com/docs/design/decisions/configuration/index.md): OINK extends Hugo and Docsy-compatible configuration without creating a second namespace or a parallel global resolver.
  - [Consumer evidence](https://oink.pgsty.com/docs/design/research/consumer-evidence/index.md): A dated corpus snapshot that shaped OINK's shells, authoring primitives, and deterministic Book migration policy.
  - [Media convergence](https://oink.pgsty.com/docs/design/proposals/media-convergence/index.md): A draft for the remaining convergence between content images, numbered figures, Landing media, and featured-image selection.
  - [2026-08-26 review](https://oink.pgsty.com/docs/design/research/2026-08-26-comprehensive-review/index.md): An evidence-based review of OINK's post-v0.7.0 implementation, configuration, outputs, security, tests, performance, bilingual contracts, and real integration site.
  - [Agent indexes](https://oink.pgsty.com/docs/design/proposals/agent-indexes/index.md): Optional per-section full-text bundles and a stable navigation JSON, built on OINK's existing Markdown outputs and navigation authority.
  - [Markdown-first authoring](https://oink.pgsty.com/docs/design/decisions/authoring/index.md): Native Markdown carries common semantics; shortcodes fill real capability gaps, and content models extend shared shells instead of forking them.
  - [Shell and navigation](https://oink.pgsty.com/docs/design/shell/index.md): Navigation authorities, immersive blog presentation, search, actions, taxonomies, indexes, and page-end composition.
  - [Book publication](https://oink.pgsty.com/docs/design/proposals/book-publication/index.md): Move Book semantic lowering and generic EPUB/PDF packaging into OINK without taking publication facts away from consumers.
  - [Config schema](https://oink.pgsty.com/docs/design/decisions/config-schema/index.md): The editor schemas are projected from the existing configuration authorities; a CI drift gate keeps them from ever becoming a third one.
  - [Landing pages](https://oink.pgsty.com/docs/design/landing/index.md): The maintainer contract for landing data, the built-in section registry, language resolution, runtime, accessibility, and outputs.
  - [Migration boundary](https://oink.pgsty.com/docs/design/migration/index.md): The supported source, configuration, and validation boundaries for migration from OINK 0.4 through OINK 1.0.0.

## Full-text bundles

- [Docs](https://oink.pgsty.com/docs/llms-full.txt)

## Site locales

- [English](https://oink.pgsty.com/index.md)
- [简体中文](https://oink.pgsty.com/zh/index.md)