Layout Templates

A layout is the template that generates the reference page for a kind of API entity — a method, property, class, enum, and so on. The manifest maps each entity type to its layout under the layouts: key. Nimbus renders one page per entity by feeding the entity’s data through its layout using Mustache syntax.

Folder vs. single file

• Entity types that support custom fields live in a folder: layouts/method/method.md is the main layout, and sibling files such as layouts/method/remarks.md define custom fields.
• Entity types without custom fields are a single file, e.g. layouts/enum/enum.md.

Page frontmatter

Each layout begins with YAML frontmatter that becomes the page’s metadata. The values are Mustache expressions resolved from the entity:

---
page-kind: api
title: "{{name}} Method"
toc-title: "{{name}}"
f1-keywords:
  - "{{fullyQualifiedName}}"
  - "{{parent.name}}.{{name}}"
index-keywords:
  - "{{name}} method"
  - "{{parent.name}}.{{name}} method"
---

Key	Purpose
page-kind	api for a generated API reference page. Omit it for a conceptual page.
title	The page title.
toc-title	A shorter title for the table of contents (optional).
f1-keywords	F1 help keywords (used by the CHM / Help Viewer output).
index-keywords	Index entries (used by the CHM / Help Viewer output).

page-kind tells the output writers how to lay the page out. MadCap Flare in particular arranges an API page as a sequence of named sections and a conceptual page as flowing prose, so a layout that omits the declaration is treated as prose. Every page layout in the default templates declares it.

The data model

Below the frontmatter, the body is Markdown with Mustache tags that pull from the entity’s data model. For the complete, per-entity-type reference of available properties, see Template Data Model. The exact fields vary by entity type, but common ones include:

Field	Meaning
{{name}}	The member’s name.
{{summary}}	The summary text.
{{namespace}}	The containing namespace.
{{parent.name}}, {{parent.typeKind}}, {{parent.link}}	The declaring type’s name, kind, and link.
{{assembly.name}}, {{assembly.fileName}}, {{assembly.link}}	Assembly details.
{{#syntax.csharp}}{{{code}}}{{/syntax.csharp}}	The C# syntax block.
{{#parameters}}{{#items}}…{{/items}}{{/parameters}}	Parameter list (name, typeHtml, description).
{{#returnValue}}{{{typeHtml}}} {{description}}{{/returnValue}}	Return value.
{{#typeParameters}}{{#items}}…{{/items}}{{/typeParameters}}	Generic type parameters.
{{#commands}}…{{/commands}}	Instrument command(s); isSingle distinguishes one command from a per-model table.
{{#supportedModels}}{{models}}{{/supportedModels}}	Supported instrument models.
{{#customFields.<name>}}{{{value}}}{{/customFields.<name>}}	Authored custom field content.

Tip

Fields ending in Html (e.g. typeHtml) are pre-formatted HTML — render them with the raw triple-brace {{{typeHtml}}} so the markup passes through.

Example: the method layout

A condensed view of the default IVI.NET method layout shows the pieces working together — sections guard optional content, lists render tables, and a custom field injects authored Remarks:

---
page-kind: api
title: "{{name}} Method"
toc-title: "{{name}}"
---

# {{parent.name}}.{{name}} Method

:::: nimbus:summary

{{summary}}

::::

:::: nimbus:syntax

## Syntax

{{#syntax.csharp}}
<pre><code class="language-csharp">{{{code}}}</code></pre>
{{/syntax.csharp}}

::::

{{#parameters}}
:::: nimbus:parameters

## Parameters

| Name | Type | Description |
|------|------|-------------|
{{#items}}
| `{{name}}` | {{{typeHtml}}} | {{description}} |
{{/items}}

::::
{{/parameters}}

{{#customFields.remarks}}
:::: nimbus:remarks

## Remarks

{{{value}}}

::::
{{/customFields.remarks}}

:::: nimbus:see-also

## See Also

- [{{parent.name}} {{parent.typeKind}}]({{parent.link}})
- [{{assembly.name}} Assembly]({{assembly.link}})

::::

Note how a Mustache section can wrap a container, so an optional section disappears entirely when the entity has nothing to show.

Marking up sections

A layout wraps each section of the page in a container, written as a fence of colons followed by nimbus: and the section name:

:::: nimbus:summary

{{summary}}

::::

In the HTML-based formats (CHM, Microsoft Help Viewer, semantic HTML, and MadCap Flare) the container renders as <div class="summary">, which stylesheets and downstream transforms target. In the Markdown and Starlight outputs the container is removed and its content retained, as those formats are Markdown and the wrapper would serve no purpose.

The nimbus: prefix identifies the container as generated structure, distinguishing it from a container authored as content.

Fence length

A container enclosing another container must use more colons than the container it encloses, as fenced code blocks do. An outer fence of equal length closes at the first inner fence, and the remaining content is reparented without error.

The default layouts use four colons for their sections, reserving three for authored content. A container nested within a section must therefore use fewer colons than the section.

Content containers

A container without the nimbus: prefix is authored content, and is preserved in every output format:

::: warning
Do not exceed the maximum input voltage.
:::

This renders as <div class="warning"> in the HTML-based formats, allowing a stylesheet to target .warning. On the Starlight web site, the names Starlight recognizes as asides (note, tip, caution, and danger) additionally render as styled callouts.

Containers are preferred to hand-written <div> elements: they are native to Markdown, and their content is parsed as Markdown.

Embedding HTML

Where Markdown cannot express the required structure — a table with merged cells, for example — HTML may be written directly. Raw HTML in a layout, a conceptual topic, or a custom field is passed through to every output format unaltered.