Advanced on OINK

Keyboard navigation

Mon, 01 Jan 0001 00:00:00 +0000

OINK ships single-key keyboard navigation on docs, blog, and Swagger pages. It is on by default, every binding yields to anything you are typing into, and a site or a single page can switch it off. The design treats the current page as the implicit sidebar cursor, reuses the rendered table of contents for section jumps, and delegates every action to an existing theme mechanism rather than building a parallel navigation state.

Search and Command Palette

Mon, 01 Jan 0001 00:00:00 +0000

OINK defaults to and recommends local search: Hugo generates a separate index per language, and Lunr plus the CJK fallback are served from same-origin assets. A site builds and searches without a public crawler, an external account, a CDN, or a network connection.

Google Custom Search and Algolia DocSearch remain as compatible integrations and are off by default. Only one search implementation can be active at a time.

Enable local search

params:
  offlineSearch: true
  offlineSearchIndex: summary # summary | content
  offlineSearchSummaryLength: 120
  offlineSearchMaxResults: 12

offlineSearch , boolean , required , default: false: Enables the local index and the Command Palette. Do not also configure gcs_engine_id or params.search.algolia.

Print support

Mon, 01 Jan 0001 00:00:00 +0000

Individual documentation pages print well from most browsers as the layouts have been styled to omit navigational chrome from the printed output. Printing one page is therefore the browser’s own Cmd/Ctrl+P; OINK offers no page-level print action of its own.

On some sites, it can be useful to enable a “print entire section” feature (as seen in this user guide). Selecting this option renders the entire current top-level section (such as Advanced for this page) with all of its child pages and sections in a format suited to printing, complete with a table of contents for the section.

AI-agent support

Mon, 01 Jan 0001 00:00:00 +0000

Early evaluation

Features described in this page are experimental, and are useful for early adoption and evaluation. Output details and validation coverage may change in future releases. To track the phased evolution of the agent-support feature, see Improve support for AI-agent doc consumption #2614.

Features

When your site opts in, these are the user-facing and machine-readable behaviors Oink enables:

Markdown output format support. Your project’s outputs configuration controls which page kinds publish Markdown.
Discovery: page HTML headers include rel="alternate" links to the Markdown version of the page.
Copy Markdown / View markdown: page actions can copy or open the Markdown version of the page when that output exists. Copy is the primary half of the split button in the breadcrumb row; the rest live in its menu.
Open in ChatGPT / Claude: file-backed page actions can hand the current browser URL to either assistant when params.ui.page_context_menu.assistant_links is explicitly enabled. Oink builds the prompt only when the reader activates the link, preserving the deployed host, query string, and fragment. The full URL then leaves the site; avoid secrets in URLs and disclose the third-party boundary. The page body is not uploaded.
View edit history: opens the current source file’s commit history when github_repo and its repository path are available.
llms.txt: site-root file listing.

The remainder of this page explains how to enable each feature, and discusses validation and metrics supported with examples.

Comments with giscus

Mon, 01 Jan 0001 00:00:00 +0000

OINK supports giscus through a Hextra-compatible comments configuration under params.comments. giscus gives each content page a comment thread backed by GitHub Discussions and lets readers comment through GitHub OAuth.

How giscus works

When a page loads, giscus searches the configured repository for a Discussion that matches the page. If it does not find one, the giscus bot creates it when a reader submits the first comment or reaction. Maintainers moderate comments in GitHub Discussions.

Analytics, user feedback, and SEO

Mon, 01 Jan 0001 00:00:00 +0000

OINK does not contact analytics, form, comment, or advertising services by default. These integrations are site decisions: enable them explicitly, document the data boundary, and provide any consent or policy required by the site’s users and jurisdiction.

Adding analytics

Hugo provides embedded templates for analytics services. When a site configures Google Analytics, browser usage information such as page views and custom events is sent to Google. This is incompatible with a fully air-gapped runtime and may be incompatible with a strict same-origin Content Security Policy.

Advanced

Mon, 01 Jan 0001 00:00:00 +0000

This chapter covers optional capabilities. Each one is enabled explicitly — the theme supplies the implementation but does not set site policy on your behalf.

In this chapter

Keyboard navigation: the complete single-key map, focus rules, and per-page opt-out
Search and Command Palette: the local index, ranking, Cmd/Ctrl-K, / full search, and \ command mode
Print output: whole-section print views
AI and agent support: Markdown output, llms.txt, page actions
Comments: giscus integration
Analytics: Google Analytics and other providers

Defaults follow the risk boundary

Local, non-networked keyboard navigation is on by default. Capabilities that change site policy or may hand data to another service remain opt-in: