Draw.io Syntax: Metadata

Purpose

This skill teaches how to build multi-page Draw.io diagrams, manage layers, attach custom properties via <object> wrappers, define file-level variables, use the %placeholder% substitution system, add tooltips and links, and enable MathJax/LaTeX rendering. It covers everything OUTSIDE the individual cell creation covered by drawio-syntax-cells.

Critical Rules (Memorize These)

1. ALWAYS use unique id values on every <diagram> element. Duplicate diagram IDs corrupt the file.
2. NEVER nest <diagram> elements inside each other. Every <diagram> is a direct child of <mxfile>.
3. ALWAYS set placeholders="1" on the <object> wrapper to enable %variable% substitution. Without it, placeholder tokens render as literal text.
4. ALWAYS use single-quoted JSON for the vars attribute on <mxfile>: vars='{"key":"value"}'. Double quotes around the attribute value break XML parsing.
5. NEVER omit the structural cells (id="0" and id="1" parent="0") on ANY page. Every <root> MUST contain both.
6. ALWAYS keep cell IDs unique across ALL pages in the file, not just within a single page.
7. ALWAYS use the full <mxfile> wrapper when the diagram needs multi-page support, file-level variables, or MathJax.
8. NEVER put id or value on the inner <mxCell> when using an <object> wrapper. These attributes belong on <object>.

Decision Tree: When Do I Need This Skill?