Templates and theming

uid: guides.templates description: Control the look of a site with page metadata, template folders, partial overrides, styles, scripts, and alert titles.

Every page is rendered through a template: a layout with partials for the header, sidebar, footer, and other regions. The built-in default template provides a responsive layout with light, dark, and automatic color themes, a searchable header, a filterable sidebar, an outline of the current article, and print styles. Most sites need only metadata and a stylesheet to make it their own.

Page metadata

Set these keys in build.globalMetadata for the whole site, in fileMetadata for groups of files, or in an article's front matter for one page.

Site identity

Layout and parts

Search engines and sharing

This site's identity is set entirely through globalMetadata:

"globalMetadata": {
  "_appTitle": "Pudu Docgen",
  "_appName": "Pudu Docgen",
  "_appLogoPath": "images/pudu-lang-short.png",
  "_appFaviconPath": "images/pudu-lang-short.png",
  "_baseUrl": "https://www.pudu-lang-docgen.com",
  "_enableSearch": true,
  "_lang": "en"
}

Landing pages

A YAML file whose first line contains YamlMime:Landing becomes a hub page on the landing layout: a banner across the full width of the page, then highlighted entry points, topic lists, and related links. Addresses are checked like links in articles, so a missing page is reported.

### YamlMime:Landing
title: Inventory service documentation
summary: Everything needed to run and extend the inventory service.
metadata:
  uid: home
  description: Guides and reference for the inventory service.

highlightedContent:
  items:
  - title: What is the inventory service?
    itemType: overview
    url: guide/introduction.md
  - title: Release notes
    itemType: whats-new
    url: https://example.org/releases

conceptualContent:
  title: Explore
  items:
  - title: Operate
    links:
    - text: Deploying
      url: guide/deploy.md
    footerLink:
      text: All operations guides
      url: guide/index.md

additionalContent:
  sections:
  - title: Related content
    items:
    - title: Pudu
      summary: The language the service is written in.
      url: https://www.pudu-lang.org/

The banner colors come from the --hero-bg custom property, which a template's public/main.css can set.

Template folders

build.template lists templates in order. The first is usually default; the others are folders in the project. A later folder replaces files of an earlier one.

"template": ["default", "template"]

A template folder may contain:

The built-in partials are head, header, sidebar, breadcrumb, actions, affix, pager, footer, and scripts. Export them with the template command to start from the originals:

pudu run Docgen.pudu template export template

Styles and scripts

The default styles are written with CSS custom properties, so a small public/main.css can restyle the whole site. This site's stylesheet lays out the footer columns and the landing page using the theme's own colors:

.footer-grid {
  display: grid;
  grid-template-columns: minmax(220px, 1.4fr) repeat(3, minmax(160px, 1fr));
  gap: 32px;
}

.content a.button-primary {
  border-color: var(--accent);
  background: var(--accent);
  color: #fff;
}

Light values are set on :root. Dark values are set on :root[data-theme="dark"] and, for the automatic theme, on :root[data-theme="auto"] inside a prefers-color-scheme: dark media query; override both to change the dark theme.

Alert titles

token.json renames alert titles. Keys are alert kinds in lower case:

{ "note": "Remarque", "warning": "Avertissement" }

Layout syntax

Layouts and partials use a logic-less template syntax:

A layout that does not parse stops the build with DG401. Export the view of each page with --exportViewModel to see every value a layout can use, including title, body, toc, navbar, breadcrumb, headings, previous, next, editUrl, lastModified, and text.

Interface language

_lang selects the interface text of the default template. English, Spanish, French, German, Portuguese, Italian, Japanese, Chinese, and Korean are built in; other languages use English. Replace individual strings with _text: