Diagrams

Notely supports four diagram and visual prototyping formats: Mermaid for text-based diagrams written in code, Excalidraw for freehand whiteboard-style drawing, Draw.io for structured technical schemas and system architectures, and Wireframe Studio for responsive low- and high-fidelity UI mockup prototyping.

Mermaid Diagrams

Mermaid lets you create diagrams using a simple text syntax. Notely renders them live in Preview and Split modes.

Insert a Mermaid Block

1. In Edit mode, click Diagram → Mermaid in the toolbar.
2. A Mermaid code block is inserted at the cursor.
3. Write your Mermaid syntax inside the block.
4. Switch to Split or Preview to see the rendered diagram.

Diagram Types

```mermaid
graph TD
    A[Open workspace] --> B[Create note]
    B --> C{Write content}
    C --> D[Save note]
    D --> E[Commit to Git]
```

Type	Keyword	Use for
Flowchart	graph TD / graph LR	Processes, decisions, flows
Sequence	sequenceDiagram	API calls, user interactions
Gantt	gantt	Project timelines
Class	classDiagram	Object relationships
State	stateDiagram-v2	State machines
ER	erDiagram	Database schemas
Pie	pie	Data proportions

Example — Git Workflow

Interactive Diagram Actions

In Preview and Split modes, hovering over any rendered Mermaid diagram reveals the top action bar:

• Edit: Opens the Mermaid visual editor modal to modify diagram elements visually.
• Download: Renders and exports the Mermaid diagram as a high-resolution PNG image saved directly to your system Downloads folder.

Troubleshooting Mermaid

If your diagram does not render:

1. Switch to Split mode to see both the source and the error message.
2. Check for syntax errors — Mermaid is strict about arrow direction (--> not →).
3. Validate with the Mermaid Live Editor.

---

Excalidraw Diagrams

Excalidraw provides a whiteboard canvas for freehand drawing, annotated shapes, and visual diagrams embedded directly in your notes.

Insert an Excalidraw Diagram

1. Click Diagram → Excalidraw in the toolbar.
2. An Excalidraw block is inserted in the note.
3. In Preview mode, the Excalidraw canvas opens.
4. Draw your diagram, then click Save to embed it.
5. The diagram is stored as a file in your workspace.

Re-Edit an Existing Diagram

1. In Preview mode, click the Edit button on the Excalidraw preview.
2. The canvas reopens with your existing drawing.
3. Make changes, then click Save.

Convert an Image to Excalidraw

You can convert any workspace image into an Excalidraw diagram so you can annotate or draw on top of it:

1. In Preview mode, right-click on any workspace image.
2. Select Edit with Excalidraw.
3. The image is placed on the Excalidraw canvas as a resizable background element.
4. Draw annotations, arrows, or labels on top.
5. Click Save to replace the image reference with the Excalidraw diagram.

Restore the Original Image

If you converted an image to Excalidraw and want to revert to the original:

1. In Preview mode, right-click the Excalidraw preview.
2. Select Restore original image.

Restore Availability

The Restore original image option only appears for Excalidraw diagrams that were created from an image conversion. Diagrams created from scratch do not show this option.

---

Draw.io Diagrams

Draw.io (diagrams.net) is integrated into Notely for precise, professional engineering schematics, UML designs, and network/cloud architectures.

Insert a Draw.io Diagram

1. Click the Insert Diagram icon (⚡) on the toolbar.
2. Click Draw.io.
3. In Preview mode, click on the placeholder to open the Draw.io editor.
4. Build your diagram and click Save Diagram.
5. The diagram saves XML source metadata to media/draw.io/*.drawio and renders a preview image to media/draw.io/*.png.

Import Diagrams via Drag and Drop

Drop any existing .drawio or .drawio.xml file directly into the Markdown Editor. Notely will parse the file, copy it into the workspace media directory, and embed it as an interactive diagram block.

---

Wireframe Studio

Wireframe Studio is Notely's integrated, visual UI prototyping tool powered by GrapesJS. It provides a drag-and-drop studio designed for rapid wireframing of desktop, tablet, and mobile user interfaces directly within your notes.

Insert a Wireframe

1. Click the Insert Diagram icon (⚡) on the Markdown toolbar.
2. Select Wireframe.
3. A wireframe placeholder markdown tag is inserted:

   ![Wireframe Diagram](media/wireframes/<diagram-id>.png){data-diagram-id="<diagram-id>"}

4. In Preview mode, click the placeholder to open Wireframe Studio.

Stencil Library & Components

The left sidebar organizes over 100 UI stencils into searchable categories:

• Layouts: Grid layouts, 2-column/3-column splits, cards, split-screens, and dashboard shells.
• Forms & Inputs: Text inputs, checkboxes, toggle switches, select dropdowns, search bars, and date pickers.
• UI Elements: Buttons, badges, breadcrumbs, tabs, avatars, pagination, tooltips, and progress bars.
• Headers & Navigation: Top navigation bars, sidebars, sub-headers, and mobile app bars.
• Hero & Content Sections: Hero banners, feature grids, CTA blocks, and pricing cards.
• Metrics & Feedback: Metric stat cards, alert banners, toast notifications, modals, and empty state cards.
• Tables & Lists: Data tables, striped tables, and interactive list groups.
• Device Frames: Browser windows, mobile phone bezels, and tablet mockups.
• FontAwesome Icons: Standard icon library elements for UI actions and navigation.

Viewport Controls & Canvas Tools

• Responsive Viewports: Switch instantly between Desktop (100%), Tablet (768px), and Mobile (375px) to verify responsive layouts.
• Zoom & Pan: Zoom in/out or fit to screen using bottom status bar controls.
• Undo / Redo: Quick hotkeys (Ctrl/Cmd + Z / Ctrl/Cmd + Y) and toolbar actions.
• Component Outlines & Guides: Toggle visual wireframe guides to inspect bounding boxes and alignment.

Inspector: Properties, Structure & Annotations

The right Inspector panel offers three dedicated modes:

1. Properties: Adjust typography, sizing, spacing, borders, background colors, and component attributes.
2. Structure: Visual DOM layer tree for inspecting parent-child component hierarchies and reordering elements.
3. Annotations: Add design notes, rationale, and UX specifications tied directly to selected wireframe blocks.

Saving & Storage

• Clicking Save Wireframe renders a PNG preview to media/wireframes/<id>.png and persists the full project structure to .notes-app/wireframes/<id>.wireframe.json.
• Wireframes are fully offline, Git-trackable, and cataloged in the Diagrams & Media Gallery (Ctrl/Cmd + Alt + M) under the UI Prototypes category.

---

Choosing a Diagram Tool

Feature	Mermaid	Excalidraw	Draw.io	Wireframe Studio
Best for	Fast text-based flows, timelines	Casual sketching, whiteboard	Engineering schematics, network charts	UI prototyping, app mockups, layout wireframes
Editing	Text syntax	Visual canvas	Visual canvas	Drag-and-drop component studio
Storage	Plain Markdown text	JSON .excalidraw + SVG	XML .drawio + PNG	JSON .wireframe.json + PNG
Offline	✓	✓	✓	✓