# Adding content

> Structure and author bilingual documentation and blog content.

---

LLMS index: [llms.txt](/llms.txt)

---

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:

```text
content/docs/content/
├── adding-content.md
└── adding-content.zh.md
```

The English file is the source page and the `.zh.md` file is its Simplified
Chinese translation. Both files share the same logical path after Hugo applies
the language suffix.

Keep generated files and files that must be copied byte-for-byte outside the
content tree. Put those in `static/` as described in
[Adding static content](#adding-static-content).

## Content sections and templates

Every top-level content directory is a Hugo section. OINK includes layouts for:

- `docs`: documentation with a section tree, table of contents, breadcrumbs,
  previous/next navigation, and repository links;
- `blog`: dated articles, taxonomy metadata, feeds, and chronological lists;
- `community`: project and contributor links;
- default pages: landing pages without the documentation sidebar.

Hugo chooses a layout from the content section. A page below `content/docs/`
therefore uses the `docs` layout. Set `type` in front matter only when a page
must use another section's layout.

### Custom sections

Create a directory below the content root, then give its pages a type when the
default layout is not sufficient:

```yaml
---
title: Architecture decisions
description: Accepted design decisions for the project.
type: docs
weight: 30
---
```

For section-wide behavior, put shared values in the section's `_index.md`
`cascade` rather than repeating them on every page. Add a project layout under
`layouts/` only when no existing OINK layout or partial is suitable.

## Doc-rooted sites <a id="alternative-site-structure"></a>

<span class="badge text-bg-info rounded-pill text-small">EXPERIMENTAL</span>

A documentation-first site can publish the `docs` section at the URL root while
keeping source files under `content/.../docs/`:

```yaml
permalinks:
  page:
    docs: /:sections[1:]/:slug/
  section:
    docs: /:sections[1:]
```

The docs section landing page then becomes the home page. Add this front matter
to the physical site-root index for each language so it can still act as a link
without competing for the same output path:

```yaml
build: { render: link }
```

### Check for path conflicts

Docs now share the URL root with blog, community, and other sections. Build with
`--printPathWarnings` and resolve every duplicate target before publishing:

```bash
hugo --printPathWarnings
```

### Legacy _docs-only_ setup

Older Docsy examples used a front matter cascade to force page types. Remove
that workaround when moving to the permalink-based doc-rooted setup; otherwise
the home page and section layouts can resolve inconsistently.

## Page front matter

Front matter is page metadata written in YAML, TOML, or JSON. OINK's sample site
uses YAML:

```yaml
---
title: Local-first architecture
linkTitle: Local-first
description: How OINK removes browser and build-time CDN dependencies.
weight: 20
date: 2026-08-08
tags: [architecture, offline]
---
```

`title` is the practical minimum. In maintained documentation, also provide a
concise `description` for search and metadata, and a `weight` when order
matters. Use `linkTitle` only when navigation needs a shorter label.

Translations should localize human-facing metadata while preserving structural
values:

```yaml
---
title: 本地优先架构
linkTitle: 本地优先
description: OINK 如何消除浏览器端与构建期的 CDN 依赖。
weight: 20
date: 2026-08-08
tags: [架构, 离线]
---
```

Do not translate keys, shortcode names, configuration keys, file paths, or
stable identifiers.

### Footer metadata

Docs and blog pages render a compact metadata block above the site footer. The
last-modified date comes from Hugo's `.Lastmod` value. Two optional front matter
fields add provenance notices:

```yaml
lastmod: 2026-08-09
upstream_attribution: https://upstream.example/docs/page/
downstream_modified: true
```

`upstream_attribution` links to the upstream source and its attribution.
`downstream_modified: true` states that the downstream project changed the page.
Omit either field when its notice does not apply.

## Page content

Write pages in Markdown unless a layout genuinely requires HTML. Hugo renders
Markdown with Goldmark and supports attributes, footnotes, tables, task lists,
render hooks, and fenced code blocks.

### Markdown

Keep source readable without the rendered site:

- use ATX headings (`## Heading`);
- put blank lines around lists, blocks, and fenced code;
- specify the language of every code fence when one exists;
- use descriptive link text and image alternative text;
- wrap prose at a review-friendly width, but never reflow code or URLs.

OINK adds render hooks for blockquote alerts and for Mermaid, math, chemistry,
Markmap, and PlantUML code blocks. See
[Diagrams and Formulae](/docs/content/diagrams-and-formulae/).

### Markup, shortcodes, and content features {#markup-and-content-features}

Use standard Markdown for ordinary prose. Use a
[shortcode](/docs/content/shortcodes/) when it supplies meaningful behavior such
as tabs, cards, a terminal recording, an API viewer, or a safe chart. Shortcodes
are part of the content contract: verify their arguments in both languages and
avoid copying rendered HTML into translations.

### Alerts

OINK supports GitHub-style blockquote alerts and optional Obsidian-style titles:

```markdown
> [!TIP]
>
> Run the translation audit before every release.

> [!WARNING] Stable anchors required
>
> A translated heading must keep the English page's rendered ID.
```

Supported semantic types include `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, and
`CAUTION`, plus the Bootstrap-compatible types and `NB`. Use alerts sparingly:
important instructions must still make sense to screen readers and in print. See
[Alerts](/docs/content/lookandfeel/#alerts) for appearance.

### Links

Use root-relative links for stable public routes and ordinary relative links for
nearby pages or bundle resources. Hugo's `ref` and `relref` shortcodes validate
content references and account for language and permalink rules:

```markdown
[Configuration]({{< ref "/docs/about/configuration" >}})
```

For bilingual pages:

- link to the logical page, not directly to a `.zh.md` filename;
- keep fragment IDs language-neutral;
- verify that both language variants resolve the same fragment;
- use `relref` when the destination must remain relative to the current host.

Run the internal-link check after changing routes or headings.

### Content style

Write task-oriented documentation in direct language. Introduce a concept before
its configuration, state defaults explicitly, and distinguish local build
verification from deployment or publication. The Chinese edition follows the
terminology and typography rules in `oink.pgsty.com/TRANSLATION.md`.

## Page bundles

A standalone page is a single Markdown file. A leaf bundle is a directory with
an `index.md` and page resources:

```text
content/docs/tutorial/
├── index.md
├── index.zh.md
├── architecture.svg
└── example.yaml
```

Both language pages can use the same image and downloadable file. Hugo normally
shares page resources across language variants on a single host, so do not
duplicate identical binary assets. Localize an image only when it contains
meaningful text; give the localized resource a clear language suffix.

Use branch bundles (`_index.md`) for sections that contain child pages and leaf
bundles (`index.md`) for terminal pages with resources.

## Adding docs, blog posts, and release notes

Create every maintained English page and its Chinese peer in the same directory:

```text
guide.md
guide.zh.md
```

For bundle pages, pair `index.md` with `index.zh.md`. Keep routing metadata,
dates, weights, aliases, and resource declarations aligned unless a
language-specific difference is intentional.

### Organizing your documentation

Use directories to reflect the reader's information architecture, not the
implementation's package tree. Each documentation subsection needs an
`_index.md` and an `_index.zh.md`. Child pages appear in the sidebar ordered by
`weight`, then by the configured fallback ordering.

Prefer a shallow hierarchy. Split a page when it serves a distinct task or
audience; do not split merely to shorten a file. See
[Organizing Your Content](/docs/content/organize-content/).

#### Docs section landing pages

A docs `_index.md` renders child-page summaries by default. Use:

```yaml
simple_list: true
```

to render a compact list, or:

```yaml
no_list: true
```

to suppress the generated list. Give each language variant a localized title and
description, and keep the structural option identical.

### Organizing blog posts and release notes

Separate posts by publisher and audience. Keep every upstream Docsy article,
including Docsy release reports, flat under `blog/docsy/`. Keep OINK-specific
articles flat under `blog/oink/`, and reserve `blog/release/` for versioned OINK
release notes. Do not add year subdirectories; pair each article in place:

```text
content/blog/
├── docsy/
│   ├── 0.16.0.md
│   ├── 0.16.0.zh.md
│   ├── hugo-upgrade.md
│   └── hugo-upgrade.zh.md
├── oink/
│   ├── implementation-diary.md
│   └── implementation-diary.zh.md
└── release/
    ├── 0.1.0.md
    └── 0.1.0.zh.md
```

A Docsy release note normally supplies a publisher-qualified `linkTitle`:

```yaml
---
title: Release 0.16.0 report and upgrade guide
linkTitle: Docsy 0.16.0 release
date: 2026-07-29
tags: [release, upgrade]
---
```

Prefix link titles for other Docsy articles with `Docsy` as well, so mixed
sidebar and list views make ownership clear.

Keep the publication date and author identity consistent across translations.
Translate the title, description, taxonomy labels, caption text, and body. Do
not translate commit IDs, release tags, commands, or URLs.

## Working with top-level landing pages

Default-layout pages are suitable for the home page, product overview, and other
destinations that do not need the docs sidebar.

### Customizing the example site pages

The bundled home page is `content/_index.md` with `content/_index.zh.md` as its
translation. It uses the same local assets and theme pipeline as the rest of
OINK. Change content and project assets in the site; do not edit vendored
runtime files merely to alter branding.

### Building your own landing pages

Compose landing pages from standard Markdown and
[`blocks/*` shortcodes](/docs/content/shortcodes/#blocks). Keep essential
information in text, make call-to-action links meaningful, and test the page at
mobile and desktop widths in both languages.

## Adding a community page

Create `community/_index.md` and `community/_index.zh.md`. The community layout
uses `params.links.user` and `params.links.developer`:

```yaml
params:
  links:
    user:
      - name: User forum
        url: https://community.example.org/
        icon: fa-solid fa-comments
        desc: Ask questions and share solutions
    developer:
      - name: GitHub
        url: https://github.com/pgsty/oink
        icon: fa-brands fa-github
        desc: Source, issues, and pull requests
```

Entries may set `rel`; OINK also adds `noopener` to external HTTP links where
appropriate. Set `params.contributingUrl` in the community page front matter if
the contribution guide is not at the conventional docs route.

## Adding static content

Files below `static/` are copied to the published root without Markdown
rendering or fingerprinting:

```text
static/reference/api/index.html
```

is published as `/reference/api/index.html`. Use this for externally generated
reference sites, verification files, and downloads that require stable names.
Prefer page resources or Hugo Pipes for assets that need resizing,
fingerprinting, or bundle-relative lookup.

OINK's browser runtime is intentionally shipped from the theme or site itself.
When adding a library, vendor and pin it, record it in `VENDOR.json`, and do not
introduce an implicit CDN fallback.

## RSS feeds

Hugo creates feeds for the home page and list sections. Disable them globally
only when the site has no feed consumers:

```yaml
disableKinds: [RSS]
```

If a section declares custom outputs, retain RSS explicitly:

```yaml
outputs:
  section: [HTML, RSS, print]
```

Check the generated language-specific feed URLs and ensure titles, summaries,
dates, canonical URLs, and `hreflang` relationships are correct.

## Sitemap

Hugo generates `sitemap.xml` by default. Site-wide settings are:

```yaml
sitemap:
  changefreq: monthly
  filename: sitemap.xml
  priority: 0.5
```

A page can override these values:

```yaml
---
title: Release notes
sitemap:
  priority: 0.8
---
```

Treat `changefreq` and `priority` as hints, not promises. Exclude drafts,
private material, and noncanonical duplicates before deployment, then inspect
the generated sitemap for every published language.