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 before writing from scratch. Every macro has pre-built examples for common diagram types and formula patterns. Load a sample, customise it - much faster than writing Mermaid syntax cold.
• Copy Source from the hover toolbar to reuse diagrams. Hover over a published diagram → click Copy Source → paste into a new macro on another page. No need to rewrite.

Mermaid 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)"].
• Pan and zoom on published diagrams. Large architecture diagrams are hard to read at default size. Hover → use Zoom In / Pan controls, or click Fullscreen for a full-screen overlay.

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.