WireViz options, metadata, and HTML templates

All document-wide WireViz options, color inheritance, metadata rules, native HTML template selection and placeholder syntax.

options configures the native diagram and parts of native HTML output. metadata holds the information that an HTML template chooses to display. Both are top-level mappings. Their exact behavior is defined by Options in 0.4.1 and the HTML generator.

Complete options reference

Field	Type	Default and behavior
`fontname`	String	`arial`; font used for native diagram and HTML. Actual availability depends on the rendering environment.
`bgcolor`	Color	`WH`; graph and HTML background.
`bgcolor_node`	Color	`WH`; common node background. If explicitly false-valued, falls back to `bgcolor`.
`bgcolor_connector`	Color	Falls back to `bgcolor_node`.
`bgcolor_cable`	Color	Falls back to `bgcolor_node`.
`bgcolor_bundle`	Color	Falls back to `bgcolor_cable`.
`color_mode`	String	`SHORT`; accepts `short`, `SHORT`, `full`, `FULL`, `hex`, `HEX`, `ger`, `GER`.
`mini_bom_mode`	Boolean	`true`; show compact BOM references for additional components in diagram boxes. False shows fuller part details.
`template_separator`	String	`.`; separates a source template from an instantiated designator in connection references.

Changing only bgcolor leaves the default bgcolor_node at white. To make nodes inherit the graph background, set bgcolor_node: null, or set both colors explicitly. Connector/cable bgcolor and bgcolor_title provide local overrides. See colors and templates.

options:
  fontname: Arial
  bgcolor: "#f5f5f5"
  bgcolor_node: WH
  bgcolor_connector: "#edf4ff"
  bgcolor_cable: WH
  bgcolor_bundle: "#fff7ed"
  color_mode: full
  mini_bom_mode: false

This fragment changes native output appearance. It is not a set of CSS rules for the browser editor, and it does not determine the interactive canvas's zoom, selection style, or saved component positions.

Metadata

Metadata accepts arbitrary keys. The common fields title, description, and notes are conventions used by templates rather than a closed schema. When title is absent, the parser uses the output name if available, otherwise WireViz diagram and BOM. An explicitly empty title is different from an omitted title.

metadata:
  title: Sensor extension
  description: Three-conductor service harness
  notes: |
    View connectors from the mating face.
    Dimensions refer to finished cable length.
  project: Bench controller
  revision: "A"
  created: "2026-09-14"

Only values referenced by the chosen HTML template become visible in that output. Quote dates and values that must remain text: PyYAML can otherwise load date-shaped values as date objects, and the scalar replacement path handles strings and numbers, not every possible YAML type. Metadata is not automatically printed as diagram nodes.

Native HTML template selection

WireViz 0.4.1 includes simple and din-6771 HTML templates. Without a template name, it uses the bundled simple.html file. To request another template:

metadata:
  title: Sensor extension
  template:
    name: din-6771
    sheetsize: A4

The native generator appends .html to metadata.template.name. Its implementation searches the output file's directory, then the library's bundled templates directory. The output directory is normally the YAML directory, but it can differ when using CLI --output-dir. This distinction matters when supplying a custom template. template.sheetsize is a template substitution value; it does not create an automatic multipage drawing system.

Custom native HTML templates are files read by the Python library. They are distinct from connector/cable templates and from the browser application's own export implementation. Do not assume that placing an HTML path in YAML causes the web application to load a local file.

HTML placeholders

Placeholder syntax is an HTML comment with spaces in exactly this form:

<h1><!-- %title% --></h1>
<p><!-- %description% --></p>
<!-- %diagram% -->
<!-- %bom% -->

The template file provides the surrounding HTML and CSS. The generator replaces placeholders; it is not a general expression or programming language.

Placeholder	Replacement
`<!-- %generator% -->`	Application name, version, and upstream URL.
`<!-- %fontname% -->`	`options.fontname`.
`<!-- %bgcolor% -->`	Hex representation of `options.bgcolor`.
`<!-- %filename% -->`	Output path and base filename.
`<!-- %filename_stem% -->`	Output basename without path.
`<!-- %diagram% -->`	Embedded SVG diagram.
`<!-- %diagram_png_b64% -->`	PNG diagram as a data URI; generate PNG output as well if the template uses it.
`<!-- %bom% -->`	BOM table with headers first.
`<!-- %bom_reversed% -->`	Reversed BOM rows with headers last.
`<!-- %sheet_current% -->`	`1` in this release.
`<!-- %sheet_total% -->`	`1` in this release.
`<!-- %template_sheetsize% -->`	`metadata.template.sheetsize`, or empty text.
`<!-- %KEY% -->`	A string or numeric metadata value named `KEY`.

For grouped metadata, a mapping of mappings is indexed in insertion order, beginning at 1:

metadata:
  authors:
    Design:
      name: Alex
      date: "2026-09-14"
    Review:
      name: Morgan
      date: "2026-09-15"

 becomes Design;  becomes Alex. The second category uses index 2. Nested scalar entries directly inside a mapping do not receive the same automatic substitution; use the documented mapping-of-mappings form. Custom keys unused by the template remain data only. Pinned template documentation.