# Getting Started

This tutorial walks through installing `shypermaid`, launching the app, and drawing a first diagram. By the end you'll have edited Mermaid code, changed the theme and direction, and saved the result as an SVG or PNG file.


# Install the package

`shypermaid` uses [`uv`](https://docs.astral.sh/uv/) for package management. Clone the repo, then run `uv sync` to create the environment and install the package with its development tools:

``` bash
git clone https://github.com/mjfrigaard/shypermaid.git
cd shypermaid
uv sync
```

`uv sync` installs the package in editable mode, along with the `dev` group from `pyproject.toml`. Changes to files in `src/shypermaid/` show up the next time the app starts.


# Launch the app

The install adds a `shypermaid` command to the environment. Run it with `uv`:

``` bash
uv run shypermaid
```

The command starts a server on `127.0.0.1:8000` and opens the app in a browser. The app ships its own copies of Mermaid and svg-pan-zoom, so it works without an internet connection. Mermaid 12 needs a current browser (Safari 17.4 or later, or a recent Chrome, Edge, or Firefox).

We can confirm the app is working by looking at the canvas. The sample flowchart from the editor should be drawn on the right side of the page.


<figure class="figure">
<p><img src="../assets/app.png" class="img-fluid figure-img" /></p>
<figcaption>The app on launch: the editor on the left and the diagram on the right.</figcaption>
</figure>


# Edit the diagram

The editor sits in the sidebar on the left. Auto-Update is on by default, so each edit redraws the canvas. Replace the sample code with the flowchart below:

``` {verbatim}
flowchart TD
    a("Write code") --> b{"Valid?"}
    b -->|"yes"| c(["Diagram"])
    b -->|"no"| d("Error message")
```

Now break the code on purpose by deleting the closing `)` on the first node. A red error message appears at the bottom of the canvas, and the last good diagram stays in place. Put the `)` back and the error goes away.


<figure class="figure">
<p><img src="../assets/error.png" class="img-fluid figure-img" /></p>
<figcaption>A parse error shows at the bottom of the canvas while the last good diagram stays in place.</figcaption>
</figure>


> **Tip: Tip**
>
> Turn off Auto-Update when you're writing a long diagram. The canvas only redraws when you click Render, so half finished lines won't flash errors while you type.


# Change how it looks

The menus at the top right of the canvas change the drawing without changing your code. Theme picks the color scheme, and Look switches between the classic style and a hand drawn style. Layout picks the engine that places the nodes: Dagre is the default, and ELK draws right angled edges and often untangles diagrams with many crossing links.

Direction rewrites your code's direction before it is drawn. Pick Left to right and the flowchart turns on its side. Pick As written to go back to the direction in your code.


<figure class="figure">
<p><img src="../assets/menus.png" class="img-fluid figure-img" /></p>
<figcaption>The same flowchart with the Forest theme, the Hand drawn look, and Left to right direction.</figcaption>
</figure>


Direction works on four diagram types, and each one sets it in its own way:

| Diagram | What Direction changes |
|----|----|
| `flowchart`, `graph` | The header, as in `flowchart LR` |
| `stateDiagram`, `classDiagram` | The top level `direction` line (added if missing) |
| `gitGraph` | The header, as in `gitGraph TB:` (no Right to left) |
| Everything else | Nothing; the diagram is drawn as written |


# Move around and save

The tool buttons on the right edge control the view. You can also drag the canvas to pan and use the scroll wheel to zoom.

| Button (tooltip) | Action |
|----|----|
| Zoom in and Zoom out | Zoom in and out |
| Actual size | Show the diagram at its actual size |
| Fit | Fit the whole diagram on the canvas |
| Fullscreen | Enter or leave fullscreen |
| Download SVG | Download the diagram as `diagram.svg` |
| Download PNG | Download the diagram as `diagram.png` at twice its size |

Hover over a button to see its name. Click Download SVG to save the diagram. The file holds the diagram as Mermaid drew it, without the pan and zoom applied. Click Download PNG for an image you can paste into slides or documents; it has a white background (dark gray with the Dark theme).


# Recap

We installed `shypermaid`, launched it with `uv run shypermaid`, and edited a flowchart in the sidebar. The menus change the theme, look, and direction, and the tool buttons control the view and save the SVG or PNG file. The [Embed the Modules](01.01-how-to-embed-modules.md) guide shows how to put the editor and viewer in your own app.
