Advanced on OINK

Multi-language support

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

OINK uses Hugo’s multilingual page model rather than site-specific domain or template assumptions. The included site makes English the primary language, and Simplified Chinese (zh) the second language.

Configure languages

Define the default language and every enabled language in hugo.yaml:

defaultContentLanguage: en

languages:
  en:
    label: English
    locale: en-US
    weight: 1
    title: Product Documentation
    params:
      description: Product guides and reference
  zh:
    label: 简体中文
    locale: zh-CN
    weight: 2
    title: 产品文档
    params:
      description: 产品指南与参考资料
      time_format_default: 2006年1月2日
      time_format_blog: 2006年1月2日

weight controls both language ordering and the selector order. label is shown in that language’s own script. locale supplies standards-friendly language tags for HTML, alternate links, and Open Graph metadata.

Search

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

OINK’s default and recommended search is local. Hugo generates a per-language index; the theme serves Lunr and its CJK fallback from same-origin assets. The site can build and search without a public crawler, external account, CDN, or network connection.

Google Custom Search and Algolia DocSearch remain compatible online integrations. They are disabled by default and should be enabled only when the site accepts their external requests, indexing, availability, and privacy boundaries.

Versioning

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

Depending on your project’s releases and versioning, you may want to let your users access previous versions of your documentation. How you deploy the previous versions is up to you. This page describes the Oink features that you can use to provide navigation between the various versions of your docs and to display an information banner on the archived sites.

If you add some [params.versions] in hugo.toml/hugo.yaml/hugo.json, the Oink adds a version selector drop-down to the navbar. You specify a URL and a name for each version you would like to add to the menu, as in the following example:

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.

Repository links and page information

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

OINK’s documentation and blog layouts can show links to the current page’s source repository:

View page source opens the source file.
Edit this page opens an editable source view.
Create child page starts a new file below the current page and can use the site’s assets/stubs/new-page-template.md template.
Create documentation issue opens an issue against the documentation repository with page context.
Create project issue optionally targets a separate product repository.

The built-in URL patterns target GitHub-style repositories. Verify every action when using another compatible host, and override the relevant partial for a different URL scheme.

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.
View Markdown: page meta area includes a View Markdown link to the Markdown version of the page.
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.

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.

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.

Advanced on OINK

Multi-language support

Configure languages

Search

Versioning

Adding a version drop-down menu

Comments with giscus

How giscus works

Analytics, user feedback, and SEO

Adding analytics

Repository links and page information

AI-agent support

Features

Print support