SOW Docs

This repository contains the bilingual docs for SOW 0.6.1, the self-contained APT / YUM package repository manager by Pigsty. It uses Hugo and the OINK docs theme, with English at / and Simplified Chinese at /zh/.

• Site: https://sow.pgsty.com
• Project: https://github.com/pgsty/sow

Layout

content/
  _index.md            # landing page metadata
  docs/                # docs, one .md (en) + one .zh.md (zh) per page
    start/             # Get Started
    tutorial/          # task-oriented walkthroughs
    feature/           # explanation: how SOW works
    command/           # complete command reference
    reference/         # sow.yml, layouts, exit codes, compatibility
  blog/
    design/            # dated architecture decisions and rationale
    release/           # release notes and announcements
data/home/{en,zh}.yaml # OINK landing-page structure and bilingual copy
data/download/sow.yaml            # install channels, assets, and release switch
data/landing/download/{en,zh}.yaml # bilingual download-page composition
layouts/_partials/                # narrow SOW-specific theme extensions
assets/scss/                      # minimal SOW download-page styles

OINK owns the common docs/blog shell, navigation, search, content blocks, and core shortcodes. Keep site-level layouts limited to SOW-specific behavior; do not copy common OINK or Docsy templates into this repository.

Theme dependency

OINK 1.3.2 is imported as a Hugo Module in hugo.yaml and pinned in go.mod. The homepage is composed by OINK from bilingual data. Docs and blog pages also render through the theme; the site keeps only product-specific data and templates.

The intentional site-level template surface is:

• data/home/{en,zh}.yaml for the OINK landing page;
• data/footer/{en,zh}.yaml for the shared footer;
• data/download/sow.yaml and data/landing/download/{en,zh}.yaml for release assets and installation choices;
• layouts/_partials/sow/content-section.html and layouts/_partials/page-meta-lastmod.html for the two site-specific rendering hooks;
• layouts/robots.txt for the deployment-specific crawler policy.

All docs/blog base templates, navigation, table of contents, search, Markdown/LLMS and print outputs, and content shortcodes resolve from OINK.

For local theme development, connect the sibling OINK checkout with the debug shortcut. It sets an inline module replacement for that command and lets Hugo select an available preview port without creating or changing a Go workspace:

make d

Local development

Install Hugo Extended 0.168.0, Go 1.27.3 or newer, and Git for the local checks.

Start the local server with:

make s

Build the static site with:

make b

Run the module verification and production build with:

make c

GitHub Actions follows stable Go releases and pins Hugo Extended 0.168.0 for production builds. SCSS uses Hugo’s built-in compiler.

The corresponding long targets are debug, serve, build, and check; make dev uses the sibling OINK checkout while make serve retains the pinned-theme preview. Do not run go mod tidy: OINK is a Hugo Module rather than an imported Go package, so tidy would remove the required theme pin.

The build is Hugo-only: OINK ships its styles, scripts, fonts, search, and content runtimes with the theme, so this repository has no Node.js or CDN build dependency.

Cloudflare Pages

Set HUGO_VERSION=0.168.0 in both the Production and Preview environments of the sow-pgsty-com Pages project. The build command is hugo, and the output directory is public. No external Sass installation is required.

The hugoVersion.min setting in hugo.yaml declares the required version; it does not install that version in Cloudflare. Without the environment variable, an older default Hugo can reject OINK's translation files. See the Cloudflare Hugo guide.

Writing conventions

This repository maintains SOW's user and design documentation. Use the writing rules of ASD-STE100, with SOW terms for software concepts. Use natural Chinese with the same meaning and sequence.

• Start with the task and its result. Present the normal workflow before alternatives.
• Introduce concepts when the reader needs them. Explain what changes, what to do next, and why.
• Use complete, active sentences. Keep necessary articles and connecting words.
• In English, use at most 20 words per instruction and 25 words per descriptive sentence.
• Give one instruction per sentence. Put conditions before the action and explanations outside the steps.
• Keep each paragraph on one topic. Remove repetition that adds no action or explanation.
• Use one term for each concept. In Chinese, use 工作区, 仓库, 包池, and 构建快照（Generation）. Keep command and field names unchanged. Dist is a named package set; Desired and Built identify its selected and built states.
• Keep local builds, HTTP serving, and target publication distinct. Put a limit next to the operation it affects.
• Use sentence case in English headings. Prefer concrete verbs to abstract nouns.

Content maintenance

• Update English .md and Chinese .zh.md pages together. Set explicit url: values, with /zh/ for Chinese.
• Preserve existing heading anchors when renaming sections. Keep historical release facts tied to their tags.
• Verify commands, defaults, configuration, and examples against SOW source and sow help. Use actual output from the matching binary for command transcripts.
• At release updates, set params.version and update the homepage, download notes, and bilingual release notes. Keep data/download/sow.yaml at published: false while the matching GitHub Release is unavailable. After publication, copy its SHA256SUMS to assets/release/sow-checksums.txt and restore that channel’s checksums_src binding. Check every filename and digest against the release, then set published: true. The Pigsty repository is a separate rolling channel.
• Keep whitespace around strong-emphasis delimiters next to Chinese prose. Run make check to check Markdown, modules, the production build, and internal links.

License

Unless otherwise noted, the docs and original site content in this repository are licensed under the Creative Commons Attribution 4.0 International License. See LICENSE for the complete legal code. Third-party software and assets retain their respective licenses; OINK itself is licensed under Apache License 2.0.

Custom anchors in Print

Page-local HTML anchors declare data-td-print-local. OINK 1.3 preserves their ordinary HTML and single-page Print IDs, and namespaces them when chapters are aggregated for Print. Keep this marker on legacy heading aliases and package-profile headings so chapters do not share IDs. Use make dev with the sibling ../oink checkout for local theme development; production builds use the published module pin.