In docmd, Templates define the foundational HTML structure, layout architecture, EJS partials, and component slots of your documentation site.

A template is an npm package declaring capabilities: ['template'] that ships custom .ejs layout files and asset bundles. The @docmd/ui resolver uses a fallback priority chain, ensuring missing slots fall back to default layouts seamlessly.

Quickstart Guide

1. Install a Template Package

npx @docmd/core add summer

2. Enable Template in Config

Set theme.name in docmd.config.json. docmd automatically detects whether the name corresponds to a built-in CSS color scheme (default, sky, ruby, retro) or a structural template package (summer, etc.):

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

Every page now renders using the summer structural layout. Unspecified slots fall back automatically to standard @docmd/ui partials.

Built-in Colour Schemes (Default Template)

The default built-in template includes four curated CSS color palettes that can be activated by setting theme.name:

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

3. Page-Level Template Overrides

Switch templates for individual pages using page frontmatter:

---
title: "Release History"
template: "template-changelog"
---

# Release History

Resolution Priority Chain

When rendering a page, docmd evaluates template paths in top-down order:

The CSS theme names default, sky, ruby, and retro are reserved color schemes. Any other identifier in theme.name is treated as a template package name.

Supported Layout Slots

Templates can override any of the 12 UI layout slots:

Asset Priority Order

When multiple templates and user stylesheets inject CSS or JS assets, the engine orders them by priority weight:

To override a template’s default CSS rules, add custom declarations to theme.customCss (Priority 15).

Template Localisation

Templates receive the active locale string during rendering. Localised text strings are resolved via the t(key) helper function using existing assets/i18n/<locale>.json translation maps.

Related Resources

• Custom Styles & Scripts—Layer custom CSS over active templates.
• Designing Custom Landing Pages—Customize home page layouts using Markdown containers.
• Configuration Reference—Overview of global site options.