Custom Fields

Custom fields carry the content authored in the Driver Designer — Remarks, Units, Front Panel notes, examples, and so on — into the generated help. The content is written per member in the help editor; the template decides where it appears on the page.

Defining a custom field

In the Markdown template system, custom fields are auto-discovered from the sibling files in a layout’s folder. For example, in the default IVI.NET template:

layouts/method/method.md      The method layout
layouts/method/remarks.md     Defines a "Remarks" custom field for methods
layouts/property/property.md   The property layout
layouts/property/remarks.md    A "Remarks" custom field for properties
layouts/property/units.md      A "Units" custom field for properties

The file name (minus .md) is the custom field’s name, and it is the name the Help Editor presents as a tab for that entity type.

The file also defines the markup surrounding the authored value on the page: the guard, the section container, and the heading.

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

## Remarks

{{{value}}}

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

The guard suppresses the entire section, including its heading, when the field is empty.

Caution

Always use the triple-brace {{{value}}} for custom field content. The double-brace {{value}} HTML-escapes the text, which would turn authored markup into visible < entities.

Placing a custom field on the page

The layout determines where a custom field appears, by referencing it:

{{> remarks}}

The reference is placed at the position the section is to occupy. In the default IVI.NET method layout, Remarks appears after the return value and before the instrument commands.

A field file that no layout references defines a field that is offered for authoring but never rendered. A reference with no corresponding file fails the help build.

Defining a Front Panel field for method pages therefore requires two files:

1. layouts/method/frontpanel.md, following the structure shown above with frontpanel in place of remarks.
2. A {{> frontpanel}} reference in layouts/method/method.md.

Both reside in the help project’s Template folder and are versioned with the driver.

Authoring custom field content

Custom fields are authored as Markdown in the embedded help editor, with a live side-by-side preview. The content is preserved through every output format. Because Markdown allows embedded HTML, raw HTML may be placed inside a custom field wherever it is needed for layout, tables, or images.

To include an image, place the file in the template’s assets/ folder and reference it with a topic-relative link, as described in The Template Manifest.

To link to a generated API topic from a custom field, use a cross-reference — see Linking to API Topics.

See Using the Help Editor for the authoring experience.