Templates

A template is an npm package that declares capabilities: ['template'] and ships a set of .ejs partial overrides plus its own CSS and JS bundle. The resolver in @docmd/ui walks a fixed priority chain to find the right partial for each slot, and falls back to the default if anything goes wrong. The build never fails because of a template issue.

Quick start

1. Install a template

# First official template ships with 0.8.7 — install via the docmd add pipeline:
npx @docmd/core add summer

2. Enable it in your config

Set one key — theme.name. docmd auto-detects whether the name refers to a reserved CSS theme (default, sky, ruby, retro) or to a template package (summer, …).

{
  "theme": {
    "name": "summer"
  }
}

Every page now uses the summer template’s layout.ejs. Slots you haven’t provided (sidebar, footer, etc.) automatically use the default @docmd/ui versions.

{
  "theme": {
    "name": "sky",
    "template": "summer"
  }
}

3. Override per page

A single frontmatter key switches the template for that page only:

---
title: "Changelog"
template: "template-changelog"
---

# Changelog
…

Resolution chain

When a page is rendered, the resolver walks this chain top-down and uses the first match:

The CSS themes default, sky, ruby, and retro are reserved — if theme.name matches one of those, it stays a CSS theme. Any other value is treated as a template name and the corresponding @docmd/template-* package is auto-loaded.

If the resolved file is missing on disk, the resolver logs a single TUI warning and falls back to the default.

Supported template slots

A template may override any of these 12 slots. Any slot you don’t override falls back to the default:

Asset priority

When multiple templates and your customCss ship CSS or JS, they load in this order (lower loads first, higher wins cascade ties):

If you want to override a template’s styles, put them in your project’s customCss at priority 15. Avoid !important in template CSS so users can override without forking.

Template localisation

The active locale is passed to your template as a normal local. Translations are looked up via the t(key) helper as in the default templates — your existing assets/i18n/<locale>.json files continue to work.

What’s Next

• Building Templates — write your own template package.
• Theming — layer customCss over any template.
• Customising Landing Pages — make a template’s home page your own.