Content and Customization on OINK

Adding Content

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

OINK uses Hugo’s content model: Markdown carries the information, front matter carries page metadata, and layouts turn both into a static site. This guide describes the conventions used by the bundled English and Simplified Chinese sample site.

Content root directory

Site content lives below content/. A multilingual site can use separate roots such as content/en/ and content/zh/, or translated filename suffixes in one mounted tree. This repository uses the second form:

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 Docsy 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.

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.

Diagrams and formulae

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

OINK supports KaTeX, Mermaid, Markmap, PlantUML, and Diagrams.net. KaTeX, Mermaid, and Markmap use build-time or same-origin resources shipped with the theme. PlantUML and the Diagrams.net editor require an explicitly configured service endpoint; they do not silently default to a public service.

LaTeX support with KaTeX

KaTeX renders TeX mathematics for the web. Hugo’s embedded KaTeX support can render formulae at build time, so readers do not need a remote math service.

Logos and Images

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

Add your logo

By default, Docsy shows a site logo at the start of the navbar, that is, at the extreme left. Place your project’s SVG logo in assets/icons/logo.svg. This overrides the default Docsy logo in the theme.

If you don’t want a logo to appear in the navbar, then set site parameter navbar_logo to false in your project’s config:

[params.ui]
navbar_logo = false

params:
  ui:
    navbar_logo: false

{
  "params": {
    "ui": {
      "navbar_logo": false
    }
  }
}

For information about styling your logo, see Styling your project logo and name.

Look and Feel

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

OINK ships a complete visual system built on Bootstrap and Docsy, with local fonts, icons, styles, and browser code. A consuming site can change tokens and project styles without rebuilding a Node dependency tree.

Project styles

Hugo Extended compiles the theme’s SCSS through Hugo Pipes. Project overrides participate in the same bundle, so production builds can minify, fingerprint, and integrity-check one same-origin stylesheet.

Project style files

Override these files in the site’s assets/scss/ directory:

Navigation and Menus

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

OINK combines Hugo’s content tree and menu model with a documentation workspace: a global navbar, a collapsible and resizable section sidebar, and a collapsible page outline. The same structure works for English, Chinese, and right-to-left languages.

The global navbar is built from Hugo’s main menu plus OINK-generated controls. Depending on configuration and page type, it can include version, language, color-mode, and search controls.

Adding `main` menu entries

Define a menu entry in page front matter:

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 Content and Customization 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.

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.

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.

Shortcodes

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

Shortcodes add behavior that ordinary Markdown cannot express. OINK retains the core Docsy components and adds locally served charts, terminal recordings, infographics, carousels, cards, and disclosure widgets. Browser runtimes load only on pages that use them.

Prefer Markdown for headings, prose, lists, links, tables, and images. A shortcode becomes part of the content API: changing its name or parameters can break every page that calls it.

Shortcode delimiters

Hugo supports two forms:

Taxonomy Support

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

Docsy supports Hugo taxonomies in its docs and blog section. You can see the default layout and can test the behavior of the generated links on this page.

Terminology

To understand the usage of taxonomies you should understand the following terminology:

Taxonomy: a categorization that can be used to classify content - e.g.: Tags, Categories, Projects, People
Term: a key within the taxonomy - e.g. within projects: Project A, Project B

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 Docsy 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 Docsy theme 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:

Content and Customization on OINK

Adding Content

Content root directory

AI-agent support

Features

Analytics, user feedback, and SEO

Adding analytics

Diagrams and formulae

LaTeX support with KaTeX

Logos and Images

Add your logo

Look and Feel

Project styles

Project style files

Navigation and Menus

Site navbar

Adding `main` menu entries

Print Support

Repository links and page information

Search

Shortcodes

Shortcode delimiters

Taxonomy Support

Terminology

Versioning

Adding a version drop-down menu

Content and Customization on OINK

Adding Content

Content root directory

AI-agent support

Features

Analytics, user feedback, and SEO

Adding analytics

Diagrams and formulae

LaTeX support with KaTeX

Logos and Images

Add your logo

Look and Feel

Project styles

Project style files

Navigation and Menus

Site navbar

Adding main menu entries

Print Support

Repository links and page information

Search

Shortcodes

Shortcode delimiters

Taxonomy Support

Terminology

Versioning

Adding a version drop-down menu

Adding `main` menu entries