Math and diagrams

Formulas and diagrams are written as plain text in the document, so they stay readable in any markdown tool. Colletta draws them in Live view and in the Split preview. Source view always shows the text as written.

Write math

Put a formula between dollar signs, the way GitHub, Obsidian and HackMD read it:

You type	You get
$E = mc^2$	a formula inside the sentence
$$ on a line, the formula, then $$ on a line	a formula on its own line, centered
a code block with the language math	the same as $$, for tools that prefer it

The area of a circle is $\pi r^2$.

$$
\int_0^1 x^2 \, dx = \frac{1}{3}
$$

You can also choose Math block or Inline math in the slash menu.

In Live view a formula is drawn as soon as the cursor leaves it. Click it, or move the cursor into it, and you see the TeX again with the dollar signs, ready to edit.

Dollar signs that aren’t math

Colletta follows the same rules as GitHub, so ordinary prices stay ordinary text:

• “It costs $20 and $30” is text, because a dollar sign followed by a digit can’t close a formula.
• A dollar sign with a space just inside it, like $ 5, doesn’t start a formula either.
• To write a dollar sign that would otherwise start a formula, type \$.
• Nothing inside code, inline code or front matter is treated as math.

When a formula has a mistake

If the TeX can’t be drawn, Colletta shows it as code with a short “Math error” message after it, so you can see what to fix. The rest of the document is unaffected.

Screen readers read formulas as math, not as a string of symbols.

Draw a diagram

Diagrams use Mermaid, a text format that GitHub, GitLab, Obsidian and HackMD also draw. Choose Diagram in the slash menu, or start a code block with the language mermaid:

```mermaid
flowchart LR
  accTitle: How a draft becomes a decision
  accDescr: A draft goes to review, then is approved or sent back.
  Draft --> Review
  Review -->|approved| Decision
  Review -->|changes| Draft
```

Flowcharts, sequence diagrams and Mermaid’s other kinds all work. The colors follow your theme, light or dark.

In Live view the diagram replaces its text when the cursor is elsewhere. Click it to edit the text; while you type, the last good drawing stays below the block so you can watch it change.

If the text has a mistake, the block stays as code with a line such as “Diagram error on line 3”, and in Live view the last good drawing stays where it was.

Make a diagram readable for everyone

Start each diagram with two lines that describe it:

• accTitle: a short name, such as “How a draft becomes a decision”.
• accDescr: a sentence or two saying what the diagram shows.

Screen readers read these instead of the drawing. A diagram without accTitle is announced only by its kind, such as “Flowchart diagram”. The slash menu’s Diagram puts in an accTitle line for you to fill in.

In the Split preview, Show source under a diagram shows its text.

What diagrams can’t do

Diagrams in Colletta never load anything from the internet, so images and icons from other sites don’t show, and links inside a diagram are plain text. Click handlers and HTML in labels are ignored too.

In other tools

Formulas and diagrams are saved as you typed them. GitHub, GitLab, Obsidian, HackMD and Typora draw both. Elsewhere they show as their text. Before moving many files, try a sample document in the tool you’re moving to. See The markdown Colletta writes.