Tips & Best Practices

Non-obvious tips that save time and prevent common rendering issues.

General Editor

• Save in the macro editor ≠ Publish the page. Clicking Save in the split-view editor stores the macro content and closes the editor. You still need to click Publish on the Confluence page for other users to see the update.
• Use the Samples dropdown (Easy Uml Diagrams) or the Formula Examples gallery (LaTeX Block Equations, Latex Inline Equations) before writing from scratch. Every macro has pre-built examples for common diagram types and formula patterns. Load one and customise it - much faster than writing diagram code cold.
• Reuse saved equations from History. LaTeX Block Equations and Latex Inline Equations both keep a history of previously entered equations (up to 50) inside the editor - reload or delete past entries instead of retyping them.

Diagrams

• The opening keyword determines the diagram type. flowchart TD creates a top-down flowchart; sequenceDiagram creates a sequence diagram. If the diagram renders incorrectly, check that the first line matches the intended type.
• Use quotes around node labels with special characters. Node labels containing parentheses, commas, or colons should be wrapped in quotes: A["Result (final)"].
• There are no zoom, pan, or fullscreen controls on a published diagram. Size large diagrams deliberately while editing (fewer nodes per diagram, shorter labels) rather than relying on post-publish viewing controls.

LaTeX Equations

• Use \\ (double backslash) for line breaks in aligned environments. A single \ is a LaTeX escape character. To break a line in a multi-step derivation, use \\.
• Use the Formula Library for standard formulas. Before writing a complex formula from scratch, check Formula Library Reference - most standard statistical, calculus, and linear algebra formulas are already there.

Performance

• Very large Gantt charts render slowly. If a Gantt chart has 50+ tasks, consider splitting it into multiple macros grouped by phase, or use a separate Confluence table for the full task list.
• ERDs with 20+ entities become hard to read. Use separate ERD macros for logical groupings (e.g., one for user/auth entities, one for content entities) rather than one giant diagram.