This is the authoring and integration reference for the OINK version pinned in go.mod. Use native Markdown and public theme interfaces before adding a local renderer, template, script or stylesheet. Upgrade mechanics and override review belong in oink-upgrade.md.
| Content | Native form | Existing HugeGraph example |
|---|---|---|
| Parallel entry points | Unordered link list + {.cards} | Server installation choices |
| Actions readers perform in order | Ordered list + {.steps} | Local preview |
| Equivalent commands or configurations | Adjacent fences with {tab="…"} | Server serializers |
| Annotated directories | filetree fence; wrap=true for complete comments | Use for actual directory layouts, keeping comments short |
| Technical catalogs | Table + {.wide}; optional .expand | Configuration |
| Architecture, dependencies or a decision flow | mermaid fence | Server installation flow |
| Text hierarchy | markmap fence | Server module outline |
| Quantitative comparison | echarts fence with its source table and test conditions | Benchmark content only when the chart clarifies a comparison |
| Screenshots inside an explanation | gallery fence | Hubble screenshots |
| Published release facts | release-card | 1.7.0 notes |
Automatic section cards already come from params.ui.section_index: cards and child-page metadata. Keep that metadata accurate instead of duplicating a section's child list. Handwritten cards suit cross-section recommendations. Keep prerequisites and warnings visible; use a native > [!DETAILS]- Title callout for supplemental detail.
Block attribute lines must touch the list, table or image they describe. Fence attributes belong on the opening fence line, after the language. The site's markup.goldmark.parser.attribute.block: true enables these markers.
- [Server](/docs/quickstart/hugegraph/hugegraph-server/) — Run the database service. - [Hubble](/docs/quickstart/toolchain/hugegraph-hubble/) — Explore and query a graph. {.cards} 1. Install the required toolchain. 1. Clone the documentation repository. 1. Run the local preview. {.steps}
OINK 1.4.0 adds compact presentation for short lists: {.cards .td-cards-list} and {.steps .td-steps-compact}. Select them where each item is brief; longer descriptions and nested commands benefit from the regular layout. Cards are unordered choices; Steps express order.
Use standard language-labelled fences, including text for plain text. Global Hugo highlighting supplies inline line numbers. Ordinary snippets do not need a filename or title bar. For one short standalone command, OINK 1.4.0 supports:
```bash {class="td-code-command" lineNos=false} scripts/hugo.sh server ```
Command strips require exactly one line, no line numbers and no collapse. Keep lineNos=false explicit because this site's global highlighting enables line numbers.
Adjacent examples of the same settings in supported formats can become tabs without a custom container:
```json {tab="JSON"} {"port": 8080} ``` ```yaml {tab="YAML"} port: 8080 ```
Give a synchronized tab set a meaningful group on the first fence and a stable value on every fence only when shared selection and persistence help readers. For long code, choose enough initially visible lines for the task (usually 5–9); do not fold short examples. Folding must preserve the complete copied source. See upstream code and Tabs for supported parameters.
```filetree {title="Store directories" wrap=true} data/ m/ # schema store: property keys and labels g/ # graph store: vertices, edges and indexes ```
Use wrap=true when readers need complete comments; keep the compact default for short comments. Do not recreate wrapping with global CSS.
| Option | Default | Meaning | | --- | --- | --- | | `auth.token_expire` | `86400` | JWT lifetime in seconds. | {.wide .expand}
.wide preserves technical identifiers while giving descriptions room. .expand adds OINK's table reader in HTML, including keyboard and close behavior; Print, Markdown and RSS keep the complete static table. Ordinary tables should remain compact. Existing .td-table--wide markers are compatible, so unrelated pages and historical source branches need no mechanical migration. Do not combine .expand with .fields, which renders a definition list. See upstream tables.
The release box is a native shortcode, not copied HTML. Its only source of version and repository facts is an exact GitHub release-tag URL in front matter:
--- title: HugeGraph 1.7.0 Release Notes date: 2025-11-16 release_url: https://github.com/apache/hugegraph/releases/tag/1.7.0 ---
{{< release-card >}}
The shortcode takes no parameters. The tag supplies the displayed version, the page‘s date supplies the release date, and OINK generates release, source tarball/ZIP and repository links locally. Confirm the URL and date against the actual release; do not point release_url at the project’s download page. The card complements HugeGraph's ASF download, signature and checksum guidance. It also has readable Print, Markdown and RSS output. See release authoring.
Use Mermaid for relationships and flows, Markmap for text outlines, and ECharts for numerical comparisons. OINK 1.4.0 gives existing Mermaid diagrams a shared reader with zoom/pan, source and SVG access; authors keep the same fence syntax. Keep required diagram resources local and let OINK load runtimes only on pages that use them. Enable another runtime only when real content needs it.
Published Markmap content is limited to text outlines and code. Its front matter allows only a finite, nonnegative spacingHorizontal; active images, links, raw HTML and other front matter fail the site's validator. ECharts needs its source table, units and test conditions alongside the chart. Keep options within the URL, HTML and CSS sinks accepted by dist/validate-site-output.py; $fn: colour callbacks require a reviewed output contract before adoption.
Use Gallery for screenshots within a tutorial. Give images meaningful alternative text and captions; keep assets local and avoid repeating the same screenshot at full width.
Use Expo only for a standalone album: a section with type: expo and cascade: {type: expo}, with leaf bundles containing index.md and local images. Resource metadata owns captions, credits and ordering. Add the matching Chinese bundle when adopting an album.
Expo supplies wall, masonry and seamless layouts. Processable local images get WebP previews fitted within 960 × 960 pixels when either dimension exceeds 960 or the source is a GIF; otherwise they reuse the original. The viewer retains the original, uses its cached preview while loading, and preloads one neighbor on either side. The first four album tiles load eagerly (the first with high priority), later tiles lazily; layout batches geometry work and uses known sizes.
Gallery has native lazy loading, asynchronous decoding and the shared viewer; Expo's generated previews, neighboring-original preload and album layout work do not apply to Gallery. Supply intrinsic width and height on standalone Markdown images to reserve space; those attributes do not compress the file. Inspect generated HTML and measure bytes/timing before claiming an improvement. See the tagged Expo implementation.
Use the optional Asciinema recorder when timing or interactive output helps, such as a startup walkthrough. Keep commands copyable. A simple version check needs no player.
Record a real session with asciinema rec demo.cast, run the commands and exit. Store the reviewed recording in static/casts/, then use:
{{< asciinema file="/casts/demo.cast" title="Startup walkthrough" speed="1" >}}
Recordings contain terminal text and timestamps. Review them for credentials and private output. Re-record when commands/output change; change title or speed only for presentation. Resize the terminal before recording: overriding player cols/rows can crop it. Check desktop and mobile playback. The recorder is an authoring tool, not a build dependency.
hugo.yaml owns appearance, search and output configuration. Four style presets are selected with params.ui.preset_menu: [paper, slate, ink, terminal]; boolean true offers only Paper/Slate. Ink and Terminal are experimental. Style and light/dark mode are independent; OINK owns saved preferences.shell/appearance-menu.html partial. Sidebar persistence uses OinkSidebar; AI integration uses the public search-tail API. Keep HugeGraph consent, version/language scope and local availability behavior in their existing hooks/adapters.params.offline_search_index: content so configuration names, error messages and other body-only terms are searchable in both languages. OINK loads the current language's index on demand; full content increases its size and first-search initialization cost. Keep accurate titles, descriptions and keywords for ranking. Run tests/e2e/search-ranking.spec.js, which preserves the 24 metadata cases and separately checks 11 body-only queries with real result clicks. Do not add keywords or boosts merely to satisfy body queries.blog_index: cards is a card index; it is distinct from blog_index: gallery with blog_gallery.mode: cards (a masonry gallery). Keep the current index until article imagery justifies another layout.The 1.4.0 release notes and tagged source are the reference for this upgrade. Consult the pinned release before extending a component; the upstream website can describe a newer version.