Home and landing pages
Configure home page content in a data file. The sections list in
data/home/<language>.yaml sets the sections and their order from top to bottom.
The theme finds each section’s content by name in the same file. An ordinary
page with layout: landing uses the same sections.
Hugo renders every section on the server. Prices, star counts, screenshots, avatars, and download states must exist in the repository before Hugo starts. No section fetches data in the browser.
If you migrate a Docsy blocks/* home page, you must rewrite it. OINK has no
blocks/cover, blocks/section, or blocks/feature shortcodes. If you retain
them, the build fails with template for shortcode "blocks/cover" not found.
Use the data/home/<language>.yaml file described here, or set
layout: landing on an ordinary page.
Where the home page’s data lives
The home page’s content file keeps only a title and a description:
Section data is a file per language:
home page data
data/
home/
- en.yamlEnglish home page
- zh.yamlChinese home page
The lookup order is data/home/<current language>.yaml → data/home/en.yaml →
data/home.yaml for a single-language site.
The file has two levels: a sections list and the named keys that the list
references.
This site uses that structure for its home page. The complete file is
data/home/en.yaml in the repository.
A minimal working home page
Create the data file below. Replace the text and links with your own content.
Put the two hero images in static/images/hero-light.webp and
static/images/hero-dark.webp. For a text-only opening, omit the entire
hero.image block. Write internal links as site paths without a leading slash.
The theme adds the current language prefix (docs/start/ → /docs/start/).
Hero
The hero is the first screen. It is the only section with a large title and an illustration.
If title_lines is absent, the hero uses title. If both are absent, it uses
the site title. The image is a CSS background. If alt is present, its
container has role="img". Otherwise, the image is hidden from assistive technology.
The setting align: center creates a text-only centered first screen. It widens
and centers the text block, balances title line breaks, and moves note below
the buttons. If an image is also present, the theme warns and falls back
to start so the image is preserved.
The section registry
There are 22 section types. Their names use hyphens. The theme normalizes
underscores in older data. Except for the hero, each type has three heading
fields, eyebrow / title / desc (or text), and a class.
| Type | What it holds |
|---|---|
hero |
The first screen: large title, buttons, a theme-following image |
metrics |
Numeric facts, with optional count animation and source links |
capabilities |
Alternating left-right capability descriptions with a dedicated visual panel |
principles |
Numbered product principles |
cards |
A general card set: features, scenarios, entry points |
logo-wall |
Tools and partners, as a grid or a pure-CSS marquee |
gallery |
A wall of screenshots |
testimonials |
Quotations with attribution |
contributors |
People, roles, avatars and links |
faq |
Questions and answers, collapsible or flat |
markdown |
Free Markdown content |
cta |
The closing call to action |
pricing |
Pricing tier cards |
pricing-compare |
A tier-by-feature comparison matrix |
command-box |
One copyable command |
steps |
An ordered procedure, optionally with commands |
timeline |
Dated milestones |
code-plate |
Code inside a presentation panel |
preview |
Markdown source beside its rendered result |
case-study |
A case: metrics plus a quotation plus a source |
download |
One or more data/download/ records |
bar-chart |
Numeric comparison without chart JavaScript |
If a type is misspelled, the build emits an unknown section type warning
and skips the section.
The commonest sections, minimally
Cards and capability panels are the most common sections. The cards section
sets its column count with columns:
The capabilities section shows one capability per screen with a structured
visual panel on the right. The visual.type must be shell, components,
code, image, or card:
Minimal YAML for the other ten scenario sections
These fragments come from the theme repository’s executable regression
fixture tests/site/data/landing/demo/en.yaml.
You can copy the field names.
The download section uses the same data/download/<key>.yaml record described
in Releases and downloads. It introduces no second
version model.
Turning any page into a landing page
Two front matter lines convert an ordinary content page to a landing page. This full-width canvas retains the navbar, command palette, and footer. It removes the sidebar and outline.
The data lives in a directory parallel to the home page’s, likewise split by language:
landing page data
data/
landing/
pricing/
- en.yaml
- zh.yaml
A non-home landing page searches for data in this order. If it finds no data, the theme warns and renders the landing shell without sections:
sectionsin the page’s front matter;data/landing/<key>/<exact language>.yaml;- The exact-language entry inside a single
data/landing/<key>.yaml; - The English or language-less record.
You can put small amounts of data in front matter. However, landing: and
sections: are mutually exclusive:
Writing a section entry
Each item in sections is either a type-name string or a map:
| Key | What it does |
|---|---|
type |
The section type. If omitted, uses key as the type |
key |
The key that supplies data. Defaults to the name in type. Use it to distinguish two instances of one section |
data |
Inline data. No top-level key lookup is needed |
id |
The section’s anchor ID, generated from key / type by default |
enabled: false |
Disables the section while keeping its data |
partial |
Uses the site’s own partial. This is a local template convention, not portable landing data |
Languages and local facts
Put descriptive text in per-language files (zh.yaml / en.yaml). A shared
fact record can also use per-field fallback: <field>_<exact language> →
<field>_<base language> → <field>. The theme normalizes - in a language
tag to _. A Chinese site resolves title_zh_cn, then title_zh, then
title. The theme does not accept camelCase suffixes.
Section display text belongs to site data. It does not use the theme’s i18n strings. Only theme controls, such as marquee pause and pricing states, use translation keys. To configure the whole multilingual site, see Languages.
A few optional facts on the landing shell are local too, written in hugo.yml
and never fetched at runtime:
The footer uses separate data in data/footer/<language>.yaml, or
data/footer.yaml for a single-language site. This site has one file per
language. If data/home/<language>.yaml still contains a footer key, the
theme warns, ignores it, and points to the new location. See
Navigation and menus for authoring instructions.
Output
| Output | What appears |
|---|---|
| HTML | The full static section content, plus landing.js loaded on demand for reveal, counting, copying and theme image switching |
| Retains content. Converts dynamic surfaces, such as the marquee, to a static grid. Removes controls | |
| Markdown | Titles, prose, lists, tables and code, with no component classes |
| RSS | Landing sections are not emitted |
If JavaScript is disabled or landing.js is unavailable, all server-rendered
sections remain visible. Metrics include their configured number formatting,
prefix, and suffix. Count animations finish on the same display text.
The marquee’s duplicate track stays outside the accessibility tree. Its pause
checkbox works without JavaScript. If the reader enables reduced motion,
movement and reveal are disabled.
Verify
- Run
hugo --printPathWarnings. This detects misspelled types, missing data keys, and simultaneouslandingandsections. - Open the home page and any landing page. Compare sections with their data files. Check every language.
- Reload with JavaScript disabled. Confirm that content remains visible without motion.
- Check light and dark modes. Confirm that
image.lightandimage.darkshow the correct images. - For a subpath deployment, confirm that all internal links and images include the prefix.
Related
- Brand and appearance — site name, logo, colors, and fonts
- Navigation and menus — navbar, footer and the language menu
- Releases and downloads — the data behind the
downloadsection - Languages — enabling languages and splitting data by language
- Configuration — full definitions of
params.ui.landing_searchand the rest